Amazon CodeCatalyst is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see [How to migrate from CodeCatalyst](migration.md). # Troubleshooting Amazon CodeCatalyst The following information can help you troubleshoot common issues in CodeCatalyst. You can also use the Amazon CodeCatalyst health report to determine if there are service issues that might be impacting your experience. **Topics** + [Troubleshooting general access issues](#troubleshooting-general) + [Troubleshooting support issues](#troubleshoot-support) + [Some or all of Amazon CodeCatalyst isn't available](#service-unavailable) + [I can't create a project in CodeCatalyst](#troubleshoot-create-project) + [I can’t access my BID space as a new user or can’t be added as a new SSO user due to truncated user name](#troubleshoot-username-truncated) + [Adding an SSO user to my federated space as a new user has created a duplicate user](#troubleshoot-username-duplicated-SSO) + [I want to submit feedback in CodeCatalyst](#troubleshoot-create-feedback) + [Troubleshooting problems with source repositories](troubleshooting-source.md) + [Troubleshooting projects and blueprints](projects-troubleshooting.md) + [Troubleshooting problems with Dev Environments](devenvironments-troubleshooting.md) + [Troubleshooting problems with workflows](troubleshooting-workflows.md) + [Troubleshooting problems with issues](troubleshooting-issues.md) + [Troubleshooting problems with search in CodeCatalyst](troubleshooting-search.md) + [Troubleshooting problems with extensions](troubleshooting-extensions.md) + [Troubleshooting problems with accounts associated with your space](troubleshooting-connections.md) + [Troubleshooting problems between Amazon CodeCatalyst and the AWS SDKs or the AWS CLI](troubleshooting-cli-sdk.md) ## Troubleshooting general access issues ### I forgot my password **Problem:** I forgot the password I use for my AWS Builder ID and Amazon CodeCatalyst. **Possible fixes:** The easiest way to fix this problem is to reset your password. 1. Open [Amazon CodeCatalyst](https://codecatalyst.aws/) and enter your **Email address**. Then, choose **Continue**. 1. Choose **Forgot password?** 1. We'll send you an email with a link for you to change your password. If you don't see the email in your inbox, check your spam folder. ### Some or all of Amazon CodeCatalyst isn't available **Problem:** I navigated to or followed a link to the CodeCatalyst console, but I see an error. **Possible fixes:** The most common reasons for this problem are that you either followed a link to a project or a space you haven't been invited to, or there is a general availability issue with the service. Check the [Health report](health-dashboard.md) to see if there are any known issues with the service. If not, contact the person who invited you to the project or space and ask for another invitation. If you haven't been invited to any projects or spaces, you can sign up and [create your own space and projects](sign-up-create-resources.md). ### I can't create a project in CodeCatalyst **Problem:** I want to create a project, but the **Create project** button shows as unavailable, or I receive an error message. **Possible fixes:**The most common reasons for this problem are that you are signed in to the console with an AWS Builder ID that doesn't have the **Space administrator** role. You must have this role to create projects in a space. If you do have this role and the button does not appear as available, there might be a transitory issue with the service. Refresh your browser and try again. ## Troubleshooting support issues ### I get an error when I access Support for Amazon CodeCatalyst **Problem:** When I choose the Support for Amazon CodeCatalyst option, I receive the following error message: **`Unable to assume role`** `To access support cases, you must add the role AWSRoleForCodeCatalystSupport to the AWS account that is the billing account for the space.` **Possible fixes:** Add the required role to the AWS account that is the billing account for the space. The account designated as the billing account for the space uses the `AWSRoleForCodeCatalystSupport` role and `AmazonCodeCatalystSupportAccess` managed policy. For more information, see [Creating the **AWSRoleForCodeCatalystSupport** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-support-create). **Note** An AWS Builder ID can only get support for the alias they are authenticated with and only for resources based on permissions in CodeCatalyst. Account and Billing support is available for all users in the space. However, builders can only get support for resources and information they have permissions for in CodeCatalyst. ### I cannot create technical support cases for my space **Problem:** I cannot create technical support cases for my space. **Fixes:** A Business Support or Enterprise Support plan needs to be added to the space billing account in order for users in the space to create technical support cases. Ask your space administrator to add an Support plan to your space billing account or visit https://repost.aws/ to ask the AWS community. ### My account for support cases is no longer connected to my space in CodeCatalyst **Problem:** My account for support cases is no longer connected to my space in CodeCatalyst. **Fixes:** If a user with the **Space administrator** role switches the space billing account, this will disconnect the Support plan and all associated cases from the space. The Support cases associated with the old space billing account will no longer be visible in Support for Amazon CodeCatalyst. The root user for that billing account can view and resolve old cases from the AWS Management Console and can set up IAM permissions for Support for other users to view and resolve old cases. You will not be able to continue to get technical support for CodeCatalyst from the old space billing account through the AWS Management Console, but you can receive technical support for other services until your Support plan is canceled. For more information, see [Updating, resolving, and reopening your case](https://docs.aws.amazon.com//awssupport/latest/user/monitoring-your-case.html) in the *Support User Guide*. ### I can't open a support case for another AWS service inSupport for Amazon CodeCatalyst **Problem:** I can’t open a support case for another AWS service in Support for CodeCatalyst. **Possible fixes:** You can only open CodeCatalyst support cases from Support for CodeCatalyst. If you need support for services or resources deployed from CodeCatalyst to another AWS, Amazon, or other third-party service, you will need to create a case through the AWS Management Console or the third-party service support channel. For more information, see [Creating support cases and case management](https://docs.aws.amazon.com//awssupport/latest/user/case-management.html) in the *Support User Guide*. ## Some or all of Amazon CodeCatalyst isn't available **Problem:** I navigated to or followed a link to the CodeCatalyst console, but I see an error. **Possible fixes:** The most common reasons for this problem are that you either followed a link to a project or a space you haven't been invited to, or there is a general availability issue with the service. Check the [Health report](health-dashboard.md) to see if there are any known issues with the service. If not, contact the person who invited you to the project or space and ask for another invitation. If you haven't been invited to any projects or spaces, you can sign up and [create your own space and projects](sign-up-create-resources.md). ## I can't create a project in CodeCatalyst **Problem:** I want to create a project, but the **Create project** button shows as unavailable, or I receive an error message. **Possible fixes:** The most common reasons for this problem are that you are signed in to the console with an AWS Builder ID that doesn't have the **Space administrator** role. You must have this role to create projects in a space. If you do have this role and the button does not appear as available, there might be a transitory issue with the service. Refresh your browser and try again. ## I can’t access my BID space as a new user or can’t be added as a new SSO user due to truncated user name **Problem:** CodeCatalyst truncates user names after 100 characters, which can cause some user names to appear identical. As a new user accessing a CodeCatalyst space, I experience this problem depending on the type of space, as follows: + I have an AWS Builder ID that I want to use to sign in to CodeCatalyst. When I attempt to sign in to the space, I get a message that my user name is not valid. + I am a federated identity administrator for a CodeCatalyst space that supports identity federation. When adding a new user to SSO users and groups in IAM Identity Center, I get a message that the user is not valid. **Possible fixes:** The first user to sign in to CodeCatalyst or be added to the space as an SSO user with a given truncated username will succeed. Any users that sign up with a AWS Builder ID or are added in IAM Identity Center after that will not be able to sign in because the name will appear to be a duplicate. Depending on the type of space, do one of the following: + To be able to sign in to the AWS Builder ID space, sign up with a different user name. + To be able to add the new user in IAM Identity Center, add the user with a different user name. **Note** Even though the user name appears to be truncated, CodeCatalyst maps to identity in a way that is not affected by user names with truncated names. However, if a user name is created that is the same as a truncated user name, that user name will not be available if another user associated (with the same space or IAM Identity Center application) has already joined CodeCatalyst with that truncated user name. ## Adding an SSO user to my federated space as a new user has created a duplicate user **Problem:** CodeCatalyst SSO users added to a CodeCatalyst space and then removed might experience an issue where the user name attempts reuse. This might result in an error similar to the following, where the user is not allowed to be duplicated even though it was re-created. **`Unable to assume role`** `To access support cases, you must add the role AWSRoleForCodeCatalystSupport to the AWS account that is the billing account for the space.` **Possible fixes:** If an existing IDC user is deleted and then a new user is recreate with the same username, then the new user is not able to log in due to the username conflicting with the old user. After a user name is added to a space as an SSO user, the name cannot be used again. Any users that sign up with a AWS Builder ID or are added in IAM Identity Center after that will not be able to sign in because the name will appear to be a duplicate. Depending on the type of space, do one of the following: + To be able to sign in to the AWS Builder ID space, sign up with a different user name. + To be able to add the new user in IAM Identity Center, add the user with a different user name. ## I want to submit feedback in CodeCatalyst **Problem:** I found a bug in CodeCatalyst and I want to submit feedback. **Possible fixes:** You can submit feedback directly in CodeCatalyst. 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. In the navigation pane, choose **Give feedback**. 1. Choose the type of feedback from the drop-down menu and enter your feedback. # Troubleshooting problems with source repositories The following information can help you troubleshoot common issues with source repositories in CodeCatalyst. **Topics** + [I have reached the maximum storage for my space and see warnings or errors](#source-troubleshoot-storage) + [I receive an error when trying to clone or push to an Amazon CodeCatalyst source repository](#source-troubleshoot-clone) + [I receive an error when trying to commit or push to an Amazon CodeCatalyst source repository](#source-troubleshoot-commit-code) + [I need a source repository for my project](#source-troubleshoot-need-repository) + [My source repository is brand-new but contains a commit](#source-troubleshoot-initial-commit) + [I want a different branch as my default branch](#source-troubleshoot-default-branch) + [I am receiving emails about activity in pull requests](#source-troubleshoot-repository-emails) + [I forgot my personal access token (PAT)](#source-troubleshoot-forgot-pat) + [A pull request doesn’t display the changes I expect](#source-troubleshoot-pull-request-diff) + [A pull request shows a status of Not mergeable](#source-troubleshoot-pull-request-not-mergeable) ## I have reached the maximum storage for my space and see warnings or errors **Problem:** I want to commit code to one or more source repositories in CodeCatalyst, but I see an error. In the console, I see a message on the source repository page that I have reached the storage limit for the space. **Possible fixes:** Depending on your role in the project or space, you can either reduce the size of one or more of your source repositories, delete unused source repositories, or change your billing tier to one that has more storage. + To reduce the size of a source repository in a project, you can delete unused branches. For more information, see [Deleting a branch](source-branches-delete.md) and [Contributor role](ipa-role-types.md#ipa-role-contributor). + To reduce the overall storage for a space, you can delete unused source repositories. For more information, see [Deleting a source repository](source-repositories-delete.md) and [Project administrator role](ipa-role-types.md#ipa-role-project-admin). + To increase the amount of storage available for your space, you can change your billing tier to one with more storage. For more information, see [Changing your CodeCatalyst billing tier](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-billing-change-plan.html) in the Amazon CodeCatalyst Administrator Guide. ## I receive an error when trying to clone or push to an Amazon CodeCatalyst source repository **Problem:** When I try to clone a source repository to a local computer or into an integrated development environment (IDE), I receive a permissions error. **Possible fixes:** You might not have a personal access token (PAT) for your AWS Builder ID, you might not have configured your credential management system with your PAT, or your PAT might have expired. Try one or more of the following solutions: + Create a personal access token (PAT). For more information, see [Grant users repository access with personal access tokens](ipa-tokens-keys.md). + Make sure you have accepted an invitation to the project that contains the source repository and that you are still a member of that project. You cannot clone a source repository if you aren’t an active member of that project. Sign in to the console and attempt to navigate to the space and the project where you're trying to clone a source repository. If you cannot see the project in the list of projects for the space, you either aren't a member of that project, or you haven't accepted an invitation to that project. For more information, see [Accepting an invitation and creating an AWS Builder ID](sign-up-sign-in.md). + Make sure your clone command is formatted correctly and includes your AWS Builder ID. For example: ``` https://LiJuan@git.us-west-2.codecatalyst.aws/v1/ExampleCorp/MyExampleProject/MyExampleRepo ``` + Use the AWS CLI to make sure that you have a PAT associated with your AWS Builder ID, and that it is not expired. If you don’t have one or the PAT is expired, create one. For more information, see [Grant users repository access with personal access tokens](ipa-tokens-keys.md). + Try creating a Dev Environment to work with the code in the source repository instead of cloning it to a local repo or IDE. For more information, see [Creating a Dev Environment](devenvironment-create.md). ## I receive an error when trying to commit or push to an Amazon CodeCatalyst source repository **Problem:** When I try to push to a source repository, I receive a permissions error. **Possible fixes:** You might not have a role in the project that allows you to commit and push code changes to the project. View your role in the project where you are trying to push changes to a source repository. For more information, see [Getting a list of members and their project roles](projects-members.md#projects-members-view) and [Granting access with user roles](ipa-roles.md). If you have a role that allows committing and pushing changes, the branch where you are trying to commit changes might have a branch rule configured for it that prevents you from pushing code changes to that branch. Try creating a branch and pushing your code to that branch instead. For more information, see [Manage allowed actions for a branch with branch rules](source-branches-branch-rules.md). ## I need a source repository for my project **Problem:** My project either doesn’t have a source repository, or I need another source repository for my project. **Possible fixes:** Some projects are created without any resources. If you are a member of the project, you can create source repositories for that project in CodeCatalyst. If someone with the **Space administrator** role installs the **GitHub Repositories** and connects it to a GitHub account, you can link to available GitHub repositories to add them to your project if you have the **Project administrator** role. For more information, see [Creating a source repository](source-repositories-create.md) and [Linking a source repository](source-repositories-link.md). ## My source repository is brand-new but contains a commit **Problem:** I just created a source repository. It should be empty, but it has a commit, a branch, and a `README.md` file in it. **Possible fixes:** This is expected behavior. All source repositories in CodeCatalyst include an initial commit that sets the default branch to `main` and includes either sample code (if the repository was created for a project using a blueprint that included sample code) or a template markdown file for a repository README file. You can create additional branches in the console and in Git clients. You can create and edit files in the console, and delete files in Dev Environments and Git clients. ## I want a different branch as my default branch **Problem:** My source repository came with a default branch named `main`, but I want a different branch as my default branch. **Possible fixes:** You cannot change or delete the default branch in source repositories in CodeCatalyst. You can create additional branches and use those branches in source actions in workflows. You can also choose to link GitHub repositories and use them as repositories for your project. ## I am receiving emails about activity in pull requests **Problem:** I didn't sign up or configure email notifications about pull request activity, but I'm receiving them anyway. **Possible fixes:** Email notifications are sent automatically about pull request activity. For more information, see [Reviewing code with pull requests in Amazon CodeCatalyst](source-pull-requests.md). ## I forgot my personal access token (PAT) **Problem:** I’ve been using a PAT for cloning, pushing, and pulling code for source repositories, but I’ve lost the value for my token, and I can’t find it in the CodeCatalyst console. **Possible fixes:** The quickest way to solve this problem is to create another PAT and configure your credential manager or IDE to use this new PAT. We only display the value of a PAT when you create it. If you lose this value, it cannot be retrieved. For more information, see [Grant users repository access with personal access tokens](ipa-tokens-keys.md). ## A pull request doesn’t display the changes I expect **Problem:** I created a pull request, but I don’t see the changes I expect to see between the source and destination branches. **Possible fixes:** This might be caused by a number of issues. Try one or more of the following solutions: + You might be reviewing the changes between older revisions, or you might not be viewing the latest changes. Refresh your browser and make sure that you’ve chosen the comparison between revisions you want to view. + Not all changes in a pull request can be displayed in the console. For example, you cannot view Git submodules in the console, so you cannot view differences in a submodule in a pull request. Some differences might be too large to display. For more information, see [Quotas for source repositories in CodeCatalyst](source-quotas.md) and [Viewing a fileViewing the history of changes to a file](source-files-view.md). + Pull requests display the differences between the merge base and whatever revision you choose. When you create a pull request, the difference displayed for you is the difference between the tip of the source branch and the tip of the destination branch. Once the pull request has been created, the displayed difference is between the revision and its merge base. The merge base is the commit that was the tip of the destination branch when the revision was created. The merge base can change between revisions. For more information about differences and merge bases in Git, see [git-merge-base](https://git-scm.com/docs/git-merge-base) in the Git documentation. ## A pull request shows a status of Not mergeable **Problem:** I want to merge a pull request, but its status shows as **Not mergeable**. **Possible fixes:** This can be caused by one or more problems: + All required reviewers for your pull request must approve a pull request before it can be merged. Review the list of required reviewers for any reviewers with a clock icon next to the name. A clock icon indicates that the reviewer hasn't approved the pull request. **Note** If a required reviewer has been removed from your project before approving the pull request, you cannot merge the pull request. Close the pull request and create a new pull request. + There might be a merge conflict between the source branch and the destination branch. CodeCatalyst does not support all possible Git merge strategies and options. You can evaluate the branches for merge conflicts in a Dev Environment or clone the repository and use an IDE or Git tools to find and resolve merge conflicts. For more information, see [Merging a pull request](pull-requests-merge.md). # Troubleshooting projects and blueprints This section can help you troubleshoot some common issues you might encounter while working with projects and blueprints in Amazon CodeCatalyst. # Java API with AWS Fargate blueprint missing dependencies for apache-maven-3.8.6 **Issue:** For a project created from the Java API with AWS Fargate blueprint, the workflow fails with an error for missing `apache-maven-3.8.6` dependencies. The workflow fails with output similar to the following example: ``` Step 8/25 : RUN wget https://dlcdn.apache.org/maven/maven-3/3.8.6/binaries/apache-maven-3.8.6-bin.tar.gz -P /tmp ---> Running in 1851ce6f4d1b [91m--2023-03-10 01:24:55-- https://dlcdn.apache.org/maven/maven-3/3.8.6/binaries/apache-maven-3.8.6-bin.tar.gz [0m[91mResolving dlcdn.apache.org (dlcdn.apache.org)... [0m[91m151.101.2.132, 2a04:4e42::644 Connecting to dlcdn.apache.org (dlcdn.apache.org)|151.101.2.132|:443... [0m[91mconnected. [0m[91mHTTP request sent, awaiting response... [0m[91m404 Not Found 2023-03-10 01:24:55 ERROR 404: Not Found. [0mThe command '/bin/sh -c wget https://dlcdn.apache.org/maven/maven-3/3.8.6/binaries/apache-maven-3.8.6-bin.tar.gz -P /tmp' returned a non-zero code: 8 [Container] 2023/03/10 01:24:55 Command failed with exit status 8 ``` **Solution:** Update the blueprint Dockerfile using the following steps. 1. In the search bar, enter `apache-maven-3.8.6` to locate the dockerfile inside the project created with the Java API with AWS Fargate blueprint. 1. Update the Dockerfile (`/static-assets/app/Dockerfile`) to use `maven:3.9.0-amazoncorretto-11` as a base image and remove the dependency on the `apache-maven-3.8.6` package. 1. (Recommended) We also recommend updating the Maven heap size to 6 GB. Below is an example Dockerfile. ``` FROM maven:3.9.0-amazoncorretto-11 AS builder COPY ./pom.xml ./pom.xml COPY src ./src/ ENV MAVEN_OPTS='-Xmx6g' RUN mvn -Dmaven.test.skip=true clean package FROM amazoncorretto:11-alpine COPY —from=builder target/CustomerService-0.0.1.jar CustomerService-0.0.1.jar EXPOSE 80 CMD ["java","-jar","-Dspring.profiles.active=prod","/CustomerService-0.0.1.jar", "—server.port=80"] ``` # Modern three-tier web application blueprint workflow **OnPullRequest** fails with permissions error for Amazon CodeGuru **Issue:** When I try to run a workflow for my project, the workflow fails to run with the following message: ``` Failed at codeguru_codereview: The action failed during runtime. View the action's logs for more details. ``` `` **Solution:** One possible cause of this action failure might be due to missing permissions in the IAM role policy, where your version of the service role used by CodeCatalyst in the connected AWS account is missing required permissions for the **codeguru\$1codereview** action to run successfully. To fix this problem, either the service role must be updated with the required permissions, or you must change the service role used for the workflow to one that has the required permissions for Amazon CodeGuru and Amazon CodeGuru Reviewer. Using the following steps, find your role and update the role policy permissions in order to allow the workflow to run successfully. **Note** These steps apply for the following workflows in CodeCatalyst: The **OnPullRequest** workflow provided for projects created with the Modern three-tier web application blueprint in CodeCatalyst. Workflows added to projects in CodeCatalyst with actions that access Amazon CodeGuru or Amazon CodeGuru Reviewer. Each project contains workflows with actions that use a role and environment provided by the AWS account connected to your project in CodeCatalyst. The workflow with the actions and their designated policy is stored in your source repository in the directory /.codecatalyst/workflows. Modifying the workflow YAML is not required unless you are adding a new role ID to the existing workflow. For information about YAML template elements and formatting, see [Workflow YAML definition](workflow-reference.md). These are the high-level steps to follow to edit your role policy and verify the workflow YAML. **To reference your role name in the workflow YAML and update the policy** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to your CodeCatalyst space. Navigate to your project. 1. Choose **CI/CD**, and then choose **Workflows**. 1. Choose the workflow titled **OnPullRequest**. Choose the **Definition** tab. 1. In the workflow YAML, in the `Role:` field under the **codeguru\$1codereview** action, make a note of the role name. This is the role with the policy that you will modify in IAM. The following example shows the role name. ![\[View the IAM role name in the workflow YAML\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/projects/ts-workflow-role.png) 1. Do one of the following: + (Recommended) Update the service role connected to your project with the required permissions for Amazon CodeGuru and Amazon CodeGuru Reviewer. The role will have a name `CodeCatalystWorkflowDevelopmentRole-spaceName` with a unique identifier appended. For more information about the role and role policy, see [Understanding the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** service role](ipa-iam-roles.md#ipa-iam-roles-service-role). Proceed to the next steps to update the policy in IAM. **Note** You must have AWS administrator access to the AWS account with the role and policy. + Change the service role used for the workflow to one that has the required permissions for Amazon CodeGuru and Amazon CodeGuru Reviewer or create a new role with the required permissions. 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). In the IAM console, find the role from step 5, such as `CodeCatalystPreviewDevelopmentRole`. 1. In the role from step 5, change the permission policy to include the `codeguru-reviewer:*` and `codeguru:*` permissions. After adding these permissions, the permission policy should look similar to the following: 1. After you make the policy corrections, return to CodeCatalyst and start the workflow run again. ## Still looking to solve your problem? You can go to [Amazon CodeCatalyst](https://codecatalyst.aws/) or fill out a [Support Feedback form](https://support.aws.amazon.com/#/contacts/aws-account-support/). In the **Request information** section, under ** How can we help you**, include that you are an Amazon CodeCatalyst customer. Provide as much detail as possible so that we can most efficiently address your issue. # Troubleshooting problems with Dev Environments Consult the following sections to troubleshoot problems related to Dev Environments. For more information about Dev Environments, see [Write and modify code with Dev Environments in CodeCatalystWrite and modify code with Dev Environments](devenvironment.md). **Topics** + [My Dev Environment creation didn't succeed due to a problem with quotas](#troubleshooting-devenvironments-create) + [I can't push changes from my Dev Environment to a specific branch in a repository](#troubleshooting-devenvironments-branchrules) + [My Dev Environment didn't resume](#troubleshooting-devenvironments-resume) + [My Dev Environment disconnected](#troubleshooting-devenvironments-connection) + [My VPC-connected Dev Environment failed](#troubleshooting-devenvironments-vpc) + [I can't find which directory my project is in](#troubleshooting-devenvironments-projects) + [I'm unable to connect to my Dev Environment via SSH](#troubleshooting-devenvironments-connect-ssh) + [I'm unable to connect to my Dev Environment via SSH because my local SSH config is missing](#troubleshooting-devenvironments-projects-ssh-config) + [I'm unable to connect to my Dev Environment via SSH because I'm having problems with my AWS Config for the `codecatalyst` profile](#troubleshooting-devenvironments-config-profile) + [I can't create a Dev Environment when I'm signed into CodeCatalyst using a single sign-on account](#troubleshoot-create-dev-env-idprovider) + [Troubleshooting problems with IDEs](devenvironments-troubleshooting-ides.md) + [Troubleshooting problems with devfiles](devenvironments-devenvironments-devfile.md) ## My Dev Environment creation didn't succeed due to a problem with quotas **Problem:** I want to create a Dev Environment in CodeCatalyst, but I see an error. In the console, I see a message on the Dev Environments page that I have reached the storage limit for the space. **Possible fixes:** Depending on your role in the project or space, you can either delete one or more of your own Dev Environments, or if you have the Space administrator role, you can delete unused Dev Environments created by other users. You can also decide to change the billing tier to one that includes more storage. + To view the storage limits, view the **Billing** tab of the Amazon CodeCatalyst space to see if the **Usage** quotas have reached the maximum allowed. If the quotas have reached the maximum, contact someone with the Space administrator role to remove unneeded Dev Environments or to consider changing the billing tier. + To remove any Dev Environments you created that you no longer need, see [Deleting a Dev Environment](devenvironment-delete.md). If the issue continues and you get an error in your IDE, check that you have a CodeCatalyst role that allows you to create a Dev Environment. The **Space administrator** role, **Project administrator** role, and **Contributor** role all have permission to create Dev Environments. For more information, see [Granting access with user roles](ipa-roles.md). ## I can't push changes from my Dev Environment to a specific branch in a repository **Problem:** I want to commit and push code changes in my Dev Environment to a branch in a source repository, but I see an error. **Possible fixes:** Depending on your role in the project or space, you might not have permissions to push code to source repositories in the project. The **Space administrator** role, **Project administrator** role, and **Contributor** role all have permission to push code to repositories in the project. If you have the **Contributor** role but cannot push code to a specific branch, there might be a branch rule configured for the specific branch that prevents users with that role from pushing code to that particular branch. Try pushing your changes to a different branch, or create a branch and then push your code to that branch. For more information, see [Manage allowed actions for a branch with branch rules](source-branches-branch-rules.md). ## My Dev Environment didn't resume **Problem:** My Dev Environment didn't resume after I stopped it. **Possible fixes:** To fix the problem, view the **Billing** tab of the Amazon CodeCatalyst space to see if the **Usage** quotas have reached the maximum limits. If the quotas have reached the maximum limit, contact your Space administrator to raise the billing tier. ## My Dev Environment disconnected **Problem:** My Dev Environment disconnected while I was using it. **Possible fixes:** To fix the problem, check your internet connection. If you are not connected to the internet, connect and resume working in your Dev Environment. ## My VPC-connected Dev Environment failed **Problem:** I associated a VPC connection to my Dev Environment and it's running into errors. **Possible fixes:** Docker uses a link layer device called a bridge network that enables containers that are connected to the same bridge network to communicate. The default bridge typically uses the `172.17.0.0/16` subnet for container networking. If the VPC subnet for your environment's instance uses the same address range that's already used by Docker, an IP address conflict might occur. To resolve an IP address conflict that's caused by Amazon VPC and Docker using the same IPv4 CIDR address block, configure a CIDR block that's different from `172.17.0.0/16`. **Note** You can't change the IP address range of an existing VPC or subnet. ## I can't find which directory my project is in **Problem:** I can't find which directory my project is in. **Possible fixes:** To locate your project, change directory to `/projects`. This is the directory where you can find your projects. ## I'm unable to connect to my Dev Environment via SSH To troubleshoot your connection to your Dev Environment via SSH, you can execute the `ssh` command with `-vvv` option to show more information on how to resolve your issue: ``` ssh -vvv codecatalyst-dev-env=== ``` ## I'm unable to connect to my Dev Environment via SSH because my local SSH config is missing If your local SSH config (`~/.ssh/config`) is missing or the contents of `Host codecatalyst-dev-env*` section is out of date, you won’t be able to connect to your Dev Environment via SSH. To troubleshoot this, delete the `Host codecatalyst-dev-env*` section and execute the first command from the **SSH Access** modal again. For more information, see [Connecting to a Dev Environment using SSH](devenvironment-connect-ssh.md). ## I'm unable to connect to my Dev Environment via SSH because I'm having problems with my AWS Config for the `codecatalyst` profile Make sure your AWS Config (`~/.aws/config`) for the `codecatalyst` profile matches the one described in [Setting up to use the AWS CLI with CodeCatalyst](set-up-cli.md). If not, delete the profile for `codecatalyst` and execute the first command from the **SSH Access** modal again. For more information, see [Connecting to a Dev Environment using SSH](devenvironment-connect-ssh.md). ## I can't create a Dev Environment when I'm signed into CodeCatalyst using a single sign-on account **Problem:** When I am signed into the CodeCatalyst console as an SSO user, I receive an unknown exception error when I choose to create a Dev Environment in the space. When I choose to create a Dev Environment and choose the IDE for access, such as AWS Cloud9, I experience issues similar to the following: + The **Dev Environments** page in the CodeCatalyst console shows the Dev Environment in the list with a `FAILED` state. + An error message similar to the following displays: **`An unknown exception happened`** `We encountered an unknown exception when launching your Dev Environment. Mention your Dev Environment id error_message_ID if you want to report or need any help.` **Possible fixes:** Dev Environments aren't available for users in spaces where Active Directory is used as the identity provider. Administrators for the space can use an alternative identity provider in order to access Dev Environments, such as IAM Identity Center. For more information about planning a space that supports identity federation, see [Planning your space that supports identity federation](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/setting-up-federation.html#setting-up-planning-federation) in the *CodeCatalyst Administrator Guide*. # Troubleshooting problems with IDEs Consult the following sections to troubleshoot problems related to IDEs in CodeCatalyst. For more information on IDEs, see [Creating a Dev Environment in an IDE](devenvironment-create.md#devenvironment-using-ide). **Topics** + [I have mismatched runtime image versions in AWS Cloud9](#troubleshooting-devenvironments-c9-runtime) + [I can't access my files in `/projects/projects` in AWS Cloud9](#troubleshooting-devenvironments-c9-filesystem) + [I can't launch my Dev Environment in AWS Cloud9 using a custom devfile](#troubleshooting-devenvironments-c9-image) + [I'm having issues in AWS Cloud9](#troubleshooting-c9) + [In JetBrains, I can't connect to my Dev Environments through CodeCatalyst](#troubleshooting-jetbrains-connect) + [I can't install AWS Toolkit for my IDE](#troubleshooting-ide-toolkit) + [In my IDE, I can't launch my Dev Environments](#troubleshooting-ide-launch) ## I have mismatched runtime image versions in AWS Cloud9 AWS Cloud9 is using different versions of the frontend asset and the backend runtime image. Using different versions might cause the Git extension and AWS Toolkit to work incorrectly. To fix the problem, navigate to the Dev Environment dashboard, stop your Dev Environment, and then start it again. To fix the problem using APIs, use the `UpdateDevEnvironment` API to update the runtime. For more information, see [UpdateDevEnvironment](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_UpdateDevEnvironment.html) in the *Amazon CodeCatalyst API reference*. ## I can't access my files in `/projects/projects` in AWS Cloud9 The AWS Cloud9 editor is unable to access files in the directory `/projects/projects`. To fix the problem, use the AWS Cloud9 terminal to access your files or move them to a different directory. ## I can't launch my Dev Environment in AWS Cloud9 using a custom devfile Your devfile image might not be compatible with AWS Cloud9. To fix the problem, review the devfile from your repository and corresponding Dev Environment and create a new one to continue. ## I'm having issues in AWS Cloud9 For other issues, check the troubleshooting section in the [AWS Cloud9 User Guide](https://docs.aws.amazon.com/cloud9/latest/user-guide/troubleshooting.html). ## In JetBrains, I can't connect to my Dev Environments through CodeCatalyst To fix the problem, check that you have only latest version of JetBrains installed. If you have multiple versions, uninstall the older versions and register your protocol handler again by closing the IDE and the browser. Then open JetBrains and register the protocol handler again. ## I can't install AWS Toolkit for my IDE To fix this problem for VS Code, manually install AWS Toolkit for Visual Studio Code from [GitHub](https://github.com/aws/aws-toolkit-vscode/releases). To fix this problem for JetBrains, manually install AWS Toolkit for JetBrains from [GitHub](https://github.com/aws/aws-toolkit-jetbrains/releases). ## In my IDE, I can't launch my Dev Environments To fix this problem for VS Code, check that you have latest version of VS Code and AWS Toolkit for Visual Studio Code installed. If you don't have the latest version, update and launch your Dev Environment. For more information, see [Amazon CodeCatalyst for VS Code](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/codecatalyst-service.html). To fix this problem for JetBrains, check that you have latest version of JetBrains and AWS Toolkit for JetBrains installed. If you don't have the latest version, update and launch your Dev Environment. For more information, see [Amazon CodeCatalyst for JetBrains](https://docs.aws.amazon.com/toolkit-for-jetbrains/latest/userguide/codecatalyst-overview.html). # Troubleshooting problems with devfiles Consult the following sections to troubleshoot problems related to devfiles in CodeCatalyst. For more information on devfiles, see [Configuring a devfile for a Dev Environment](devenvironment-devfile.md). **Topics** + [My Dev Environment is using the default universal devfile even though I have implemented a custom image in a custom devfile](#troubleshooting-devenvironments-custom-image) + [My project is not building in my Dev Environment with the default universal devfile](#troubleshooting-devenvironments-default-image) + [I want to move a repository devfile for a Dev Environment](#troubleshooting-devenvironments-devfile-moving) + [I'm having a problem starting my devfile](#troubleshooting-devenvironments-devfile-recovery) + [I'm not sure how to check my devfile status](#troubleshooting-devenvironments-devfile-status) + [My devfile is not compatible with the tooling provided in the latest image](#troubleshooting-devenvironments-devfile-version) ## My Dev Environment is using the default universal devfile even though I have implemented a custom image in a custom devfile If CodeCatalyst encounter errors while starting a Dev Environment that is using a custom devfile, the Dev Environment defaults to the default universal devfile. To fix the problem, you can check the exact error in the logs under `/aws/mde/logs/devfile.log`. You can also check if `postStart` execution was successful in your logs: `/aws/mde/logs/devfileCommand.log`. ## My project is not building in my Dev Environment with the default universal devfile To fix the problem check that you are not using a custom devfile. If you are not using a custom devfile, view the `devfile.yaml` file in the source repository of the project to locate and fix any errors. ## I want to move a repository devfile for a Dev Environment You can move the default devfile in `/projects/devfile.yaml` to your source code repository. To update the location of the devfile, use following command: `/aws/mde/mde start --location repository-name/devfile.yaml`. ## I'm having a problem starting my devfile If there's a problem starting your devfile, it will enter recovery mode so that you can still connect to your environment and fix your devfile. While in recovery mode, running `/aws/mde/mde status` won’t contain the location of your devfile. ``` { "status": "STABLE" } ``` You can check the error in the logs under `/aws/mde/logs`, fix the devfile, and try running `/aws/mde/mde start` again. ## I'm not sure how to check my devfile status You can check your devfile status by running `/aws/mde/mde status`. After running this command, you may see one of the following: + `{"status": "STABLE", "location": "devfile.yaml" }` This indicates that your devfile is correct. + `{"status": "STABLE" }` This indicates that your devfile is could not start and has entered recovery mode. You can check the exact error in the logs under `/aws/mde/logs/devfile.log`. You can also check if `postStart` execution was successful in your logs: `/aws/mde/logs/devfileCommand.log`. For more information, see [Specifying universal devfile images for a Dev Environment](devenvironment-universal-image.md). ## My devfile is not compatible with the tooling provided in the latest image In your Dev Environment, `devfile` or `devfile postStart` may fail if the `latest` tooling does not have the tooling required for a specific project. To fix the problem, do the following: 1. Navigate to your devfile. 1. In your devfile, update to a granular image version instead of `latest`. It may look similar to the following: ``` components: - container: image: public.ecr.aws/amazonlinux/universal-image:1.0 ``` 1. Create a new Dev Environment using the updated devfile. # Troubleshooting problems with workflows Consult the following sections to troubleshoot problems related to workflows in Amazon CodeCatalyst. For more information about workflows, see [Build, test, and deploy with workflowsBuild, test, and deploy with workflows](workflow.md). **Topics** + [How do I fix "Workflow is inactive" messages?](#troubleshooting-workflows-inactive) + [How do I fix "Workflow definition has *n* errors" errors?](#troubleshooting-workflows-asterisks) + [How do I fix "Unable to locate credentials" and "ExpiredToken" errors?](#troubleshooting-workflows-auth-errors-eks) + [How do I fix "Unable to connect to the server" errors?](#troubleshooting-workflows-unable-connect-eks) + [Why are CodeDeploy fields missing from the visual editor?](#troubleshooting-workflows-codedeploy) + [How do I fix IAM capabilities errors?](#troubleshooting-workflows-capabilities) + [How do I fix "npm install" errors?](#troubleshooting-workflows-npm) + [Why do multiple workflows have the same name?](#troubleshooting-workflows-name) + [Can I store my workflow definition files in another folder?](#troubleshooting-workflows-folder) + [How do I add actions in sequence to my workflow?](#troubleshooting-workflows-visual) + [Why does my workflow successfully validate but fail at runtime?](#troubleshooting-workflows-validation) + [Auto-discovery doesn't discover any reports for my action](#troubleshooting-reports-auto-discovery) + [My action fails on auto-discovered reports after I configure success criteria](#troubleshooting-success-auto-discovery) + [Auto-discovery generates reports that I don't want](#troubleshooting-unwanted-auto-discovery) + [Auto-discovery generates many small reports for a single test framework](#troubleshooting-reports-combined) + [Workflows listed under CI/CD don't match those in the source repository](#troubleshooting-workflow-source) + [I can't create or update workflows](#troubleshooting-workflows-branchrules) ## How do I fix "Workflow is inactive" messages? **Problem**: In the CodeCatalyst console, under **CI/CD**, **Workflows**, your workflow appears with the following message: `Workflow is inactive.` This message indicates that the workflow definition file contains a trigger that doesn't apply to the branch that you're currently on. For example, your workflow definition file might contain a `PUSH` trigger that references your `main` branch, but you're on a feature branch. Since the changes you're making in your feature branch don't apply to `main`, and will not start workflow runs in `main`, CodeCatalyst decommissions the workflow on the branch and marks it as `Inactive`. **Possible fixes**: If you want to start a workflow on your feature branch, you can do the following: + In your feature branch, in the workflow definition file, remove the `Branches` property from the `Triggers` section so that it looks like this: ``` Triggers: - Type: PUSH ``` This configuration causes the trigger to activate on a push to any branch, including your feature branch. If the trigger is activated, CodeCatalyst will start a workflow run using the workflow definition file and source files in whatever branch you're pushing to. + In your feature branch, in the workflow definition file, remove the `Triggers` section and run the workflow manually. + In your feature branch, in the workflow definition file, change the `PUSH` section so that it references your feature branch rather than another branch (like `main`, for example). **Important** Be careful not to commit these changes if you don't intend to merge them to back to your `main` branch. For more information about editing the workflow definition file, see [Creating a workflow](workflows-create-workflow.md). For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md). ## How do I fix "Workflow definition has *n* errors" errors? **Problem**: You see any of the following error messages: **Error 1:** In the **CI/CD**, **Workflows** page, under your workflow's name, you see: `Workflow definition has n errors` **Error 2:** While editing a workflow, you choose the **Validate** button and the following message appears at the top of the CodeCatalyst console: `The workflow definition has errors. Fix the errors and choose Validate to verify your changes.` **Error 3:** After navigating to your workflow's details page, you see the following error in the **Workflow definition** field: `n errors` **Possible fixes**: + Choose **CI/CD**, choose **Workflows**, and choose the name of the workflow that has the error. In the **Workflow definition** field near the top, choose the link to the error. Details about the error appear at the bottom of the page. Follow the troubleshooting tips in the error to fix the issue. + Make sure that the workflow definition file is a YAML file. + Make sure that the YAML properties in the workflow definition file are nested at the right level. To see how properties should be nested in the workflow definition file, refer to the [Workflow YAML definition](workflow-reference.md), or consult your action's documentation, which is linked to from [Adding an action to a workflow](workflows-add-action.md). + Make sure that asterisks (`*`) and other special characters are escaped properly. To escape them, add single or double quotes. For example: ``` Outputs: Artifacts: - Name: myartifact Files: - "**/*" ``` For more information about special characters in the workflow definition file, see [Syntax guidelines and conventions](workflow-reference.md#workflow.terms.syntax.conv). + Make sure that the YAML properties in the workflow definition file use the right capitalization. For more information about casing rules, see [Syntax guidelines and conventions](workflow-reference.md#workflow.terms.syntax.conv). To determine the correct casing of each property, refer to the [Workflow YAML definition](workflow-reference.md), or consult your action's documentation, which is linked to from [Adding an action to a workflow](workflows-add-action.md). + Make sure that the `SchemaVersion` property is present and set to the correct version in the workflow definition file. For more information, see [SchemaVersion](workflow-reference.md#workflow.schemaversion). + Make sure that the `Triggers` section in the workflow definition file includes all required properties. To determine the required properties, choose the trigger in the [visual editor](workflow.md#workflow.editors) and look for fields that are missing information, or consult the trigger reference documentation at [Triggers](workflow-reference.md#triggers-reference). + Make sure that the `DependsOn` property in the workflow definition file is properly configured and does not introduce circular dependencies. For more information, see [Sequencing actions](workflows-depends-on.md). + Make sure that the `Actions` section in the workflow definition file includes at least one action. For more information, see [Actions](workflow-reference.md#actions-reference). + Make sure that each action includes all required properties. To determine the required properties, choose the action in the [visual editor](workflow.md#workflow.editors) and look for fields that are missing information, or consult your action's documentation, which is linked to from [Adding an action to a workflow](workflows-add-action.md). + Make sure that all input artifacts have corresponding output artifacts. For more information, see [Defining an output artifact](workflows-working-artifacts-output.md). + Make sure that variables defined in one action are exported so that they can be used in other actions. For more information, see [Exporting a variable so that other actions can use it](workflows-working-with-variables-export-input.md). ## How do I fix "Unable to locate credentials" and "ExpiredToken" errors? **Problem**: While working through [Tutorial: Deploy an application to Amazon EKS](deploy-tut-eks.md), you see one or both of the following error messages in your development machine's terminal window: `Unable to locate credentials. You can configure credentials by running "aws configure".` `ExpiredToken: The security token included in the request is expired` **Possible fixes**: These errors indicate that the credentials that you're using to access AWS services have expired. In this case, do not run the `aws configure` command. Instead, use the following instructions to refresh your AWS access key and session token. **To refresh your AWS access key and session token** 1. Make sure you have the AWS access portal URL, username, and password for the user that you're using the complete the Amazon EKS tutorial (`codecatalyst-eks-user`). You should have configured these items when you completed [Step 1: Set up your development machine](deploy-tut-eks.md#deploy-tut-eks-dev-env-create) of the tutorial. **Note** If you do not have this information, go to the `codecatalyst-eks-user` details page in IAM Identity Center, choose **Reset password**, **Generate a one-time password [...]**, and **Reset password** again to display the information on the screen. 1. Do one of the following: + Paste the AWS access portal URL into your browser's address bar. Or + Refresh the AWS access portal page if it's already loaded. 1. Sign in with the `codecatalyst-eks-user`'s username and password, if you're not already signed in. 1. Choose **AWS account**, and then choose the name of the AWS account to which you assigned the `codecatalyst-eks-user` user and permission set. 1. Next to the permission set name (`codecatalyst-eks-permission-set`), choose **Command line or programmatic access**. 1. Copy the commands in the middle of the page. They look similar to the following: ``` export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE" export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" export AWS_SESSION_TOKEN="session-token" ``` ...where *session-token* is a long random string. 1. Paste the commands into your terminal prompt on your development machine and press Enter. The new keys and session token are loaded. You have now refreshed your credentials. The AWS CLI, `eksctl`, and `kubectl` commands should now work. ## How do I fix "Unable to connect to the server" errors? **Problem**: While working through the tutorial described in [Tutorial: Deploy an application to Amazon EKS](deploy-tut-eks.md), you see an error message similar to the following in your development machine's terminal window: `Unable to connect to the server: dial tcp: lookup long-string.gr7.us-west-2.eks.amazonaws.com on 1.2.3.4:5: no such host` **Possible fixes**: This error usually indicates that the credentials that the `kubectl` utility is using to connect to your Amazon EKS cluster have expired. To solve the issue, refresh the credentials by entering the following command at the terminal prompt: ``` aws eks update-kubeconfig --name codecatalyst-eks-cluster --region us-west-2 ``` Where: + *codecatalyst-eks-cluster* is replaced with the name of your Amazon EKS cluster. + *us-west-2* is replaced with the AWS Region where your cluster is deployed. ## Why are CodeDeploy fields missing from the visual editor? **Problem**: You are using a [Deploy to Amazon ECS](deploy-action-ecs.md) action, and you are not seeing the CodeDeploy fields such as **CodeDeploy AppSpec** in the workflow's visual editor. This problem may occur because the Amazon ECS service that you specified in the **Service** field is not configured to perform blue/green deployments. **Possible fixes**: + Choose a different Amazon ECS service on the **Deploy to Amazon ECS** action's **Configuration** tab. For more information, see [Deploying to Amazon ECS with a workflow](deploy-action-ecs.md). + Configure the selected Amazon ECS service to perform blue/green deployments. For more information about configuring blue/green deployments, see [Blue/Green deployment with CodeDeploy](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-type-bluegreen.html) in the *Amazon Elastic Container Service Developer Guide*. ## How do I fix IAM capabilities errors? **Problem**: You are using a [Deploy CloudFormation stack](deploy-action-cfn.md) action, and you see `##[error] requires capabilities: [capability-name]` in your **Deploy CloudFormation stack** action's logs. **Possible fixes**: Complete the following procedure to add the capability to the workflow definition file. For more information about IAM capabilities, see [Acknowledging IAM resources in CloudFormation templates](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-template.html#using-iam-capabilities) in the *IAM User Guide*. ------ #### [ Visual ] **To add an IAM capability using the visual editor** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Choose your project. 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status. 1. Choose **Edit**. 1. Choose **Visual**. 1. In the workflow diagram, choose your **Deploy CloudFormation stack** action. 1. Choose the **Configuration** tab. 1. At the bottom, choose **Advanced - optional**. 1. In the **Capabilities** drop-down list, select the check box next to the capability mentioned in the error message. If the capability is not available in the list, use the YAML editor to add it. 1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing. 1. Choose **Commit**, enter a commit message, and choose **Commit** again. 1. If a new workflow run doesn't start automatically, run the workflow manually to see if the changes fix the error. For more information about running a workflow manually, see [Starting a workflow run manually](workflows-manually-start.md). ------ #### [ YAML ] **To add an IAM capability using the YAML editor** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Choose your project. 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status. 1. Choose **Edit**. 1. Choose **YAML**. 1. In the **Deploy CloudFormation stack** action, add a `capabilities` property, like this: ``` DeployCloudFormationStack: Configuration: capabilities: capability-name ``` Replace *capability-name* with the name of the IAM capability shown in the error message. Use commas and no spaces to list multiple capabilities. For more information, see the description of the `capabilities` property in the ['Deploy CloudFormation stack' action YAML](deploy-action-ref-cfn.md). 1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing. 1. Choose **Commit**, enter a commit message, and choose **Commit** again. 1. If a new workflow run doesn't start automatically, run the workflow manually to see if the changes fix the error. For more information about running a workflow manually, see [Starting a workflow run manually](workflows-manually-start.md). ------ ## How do I fix "npm install" errors? **Problem**: Your [AWS CDK deploy action](cdk-dep-action.md) or [AWS CDK bootstrap action](cdk-boot-action.md) fails with an `npm install` error. This error may occur because you are storing your AWS CDK app dependencies in a private node package manager (npm) registry that cannot be accessed by the action. **Possible fixes**: Use the following instructions to update your AWS CDK app's `cdk.json` file with additional registry and authentication information. **Before you begin** 1. Create secrets for your authentication information. You'll reference these secrets in the `cdk.json` file instead of providing the cleartext equivalents. To create the secrets: 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Choose your project. 1. In the navigation pane, choose **CI/CD**, and then choose **Secrets**. 1. Create two secrets with the following properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/troubleshooting-workflows.html) For more information about secrets, see [Masking data using secrets](workflows-secrets.md). 1. Add the secrets as environment variables to your AWS CDK action. The action will replace the variables with real values when it runs. To add the secrets: 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status. 1. Choose **Edit**. 1. Choose **Visual**. 1. In the workflow diagram, choose your AWS CDK action. 1. Choose the **Inputs** tab. 1. Add two variables with the following properties: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/troubleshooting-workflows.html) You now have two variables containing references to secrets. Your workflow definition file YAML code should look similar to the following: **Note** The following code sample is from an **AWS CDK bootstrap** action; a **AWS CDK deploy** action will look similar. ``` Name: CDK_Bootstrap_Action SchemaVersion: 1.0 Actions: CDKBootstrapAction: Identifier: aws/cdk-bootstrap@v2 Inputs: Variables: - Name: NPMUSER Value: ${Secrets.npmUsername} - Name: NPMTOKEN Value: ${Secrets.npmAuthToken} Sources: - WorkflowSource Environment: Name: Dev2 Connections: - Name: account-connection Role: codecatalystAdmin Configuration: Parameters: Region: "us-east-2" ``` You are now ready to use the `NPMUSER` and `NPMTOKEN` variables in your `cdk.json` file. Go to the next procedure. **To update your cdk.json file** 1. Change to the root directory of your AWS CDK project, and open the `cdk.json` file. 1. Find the `"app":` property, and change it to include the code shown in *red italics*: **Note** The following sample code is from a TypeScript project. If you're using a JavaScript project, the code will look similar though not identical. ``` { "app": "npm set registry=https://your-registry/folder/CDK-package/ --userconfig .npmrc && npm set //your-registry/folder/CDK-package/:always-auth=true --userconfig .npmrc && npm set //your-registry/folder/CDK-package/:_authToken=\"${NPMUSER}\":\"${NPMTOKEN}\" && npm install && npx ts-node --prefer-ts-exts bin/hello-cdk.ts|js", "watch": { "include": [ "**" ], "exclude": [ "README.md", "cdk*.json", "**/*.d.ts", "**/*.js", "tsconfig.json", "package*.json", ... ``` 1. In the code highlighted in *red italics*, replace: + *your-registry/folder/CDK-package/* with the path to your AWS CDK project dependencies in your private registry. + *hello-cdk.ts\$1.js* with the name of your entrypoint file. This may be a `.ts` (TypeScript) or `.js` (JavaScript) file depending on the language you're using. **Note** The action will replace the *NPMUSER* and *NPMTOKEN* variables with the npm username and access token that you specified in **Secrets**. 1. Save your `cdk.json` file. 1. Re-run the action manually to see if the changes fix the error. For more information about running actions manually, see [Starting a workflow run manually](workflows-manually-start.md). ## Why do multiple workflows have the same name? Workflows are stored per branch per repository. Two different workflows can have the same name if they exist in different branches. In the Workflows page, you can differentiate workflows of the same name by looking at the branch name. For more information, see [Organizing your source code work with branches in Amazon CodeCatalyst](source-branches.md). ![\[Workflow branch\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/workflow-branch.png) ## Can I store my workflow definition files in another folder? No, you must store all workflow definition files in the `.codecatalyst/workflows` folder, or in subfolders of that folder. If you are using a mono repo with multiple logical projects, place all your workflow definition files in the `.codecatalyst/workflows` folder or one of its subfolders, and then use the **Files changed** field (visual editor) or `FilesChanged` property (YAML editor) inside a trigger to trigger the workflow automatically at a specified project path. For more information, see [Adding triggers to workflows](workflows-add-trigger-add.md) and [Example: A trigger with a push, branches, and files](workflows-add-trigger-examples.md#workflows-add-trigger-examples-push-multi). ## How do I add actions in sequence to my workflow? By default, when you add an action to your workflow, it will have no dependencies and will run in parallel with other actions. If you want to arrange actions in sequence, you can set a dependency on another action by setting the `DependsOn` field. You can also configure an action to consume artifacts or variables which are outputs of other actions. For more information, see [Sequencing actions](workflows-depends-on.md). ## Why does my workflow successfully validate but fail at runtime? If you validated your workflow using the `Validate` button, but your workflow failed anyway, it might because a limitation in the validator. Any errors in reference to a CodeCatalyst resource like secrets, environments, or fleets in the workflow configuration will not register during a commit. If any references that aren't valid are used, the error will only be identified when a workflow is run. Similarly, if there are any errors in your action configuration like missing a required field or typos in action attributes, they will be identified only when the workflow is run. For more information, see [Creating a workflow](workflows-create-workflow.md). ## Auto-discovery doesn't discover any reports for my action **Problem:** I configured auto-discovery for an action that runs tests, but no reports are discovered by CodeCatalyst. **Possible fixes:** This might be caused by a number of issues. Try one or more of the following solutions: + Make sure that the tool used to run tests produces outputs in one of the formats that CodeCatalyst understands. For example, if you would like `pytest` to allow CodeCatalyst to discover test and code coverage reports, include the following arguments: ``` --junitxml=test_results.xml --cov-report xml:test_coverage.xml ``` For more information, see [Quality report types](test-workflow-actions.md#test-reporting). + Make sure that the file extension for the outputs are consistent with the chosen format. For example, when configuring `pytest` to produce results in `JUnitXML` format, check that the file extension is `.xml`. For more information, see [Quality report types](test-workflow-actions.md#test-reporting). + Make sure that `IncludePaths` is configured to include the entire file system (`**/*`) unless you are excluding certain folders on purpose. Similarly, make sure that `ExcludePaths` don't exclude directories where you expect your reports to be located. + If you manually configured a report to use a specific output file, it will be excluded from auto-discovery. For more information, see [Quality reports YAML example](test-config-action.md#test.success-criteria-example). + Auto-discovery may not find reports because the action failed before any outputs were generated. For example, the build may have failed before any unit tests have been run. ## My action fails on auto-discovered reports after I configure success criteria **Problem:** When I enable auto-discovery and configure success criteria, some of the reports don't meet the success criteria and the action fails as a result. **Possible fixes:** To resolve this, try one or more of the following solutions: + Modify `IncludePaths` or `ExcludePaths` to exclude reports that you are not interested in. + Update success criteria to allow all reports to pass. For example, if two reports were discovered with one having line coverage of 50% and another one of 70%, adjust the minimum line coverage to 50%. For more information, see [Success criteria](test-best-practices.md#test.best-success-criteria) + Turn the failing report into a manually configured report. This allows you to configure different success criteria for that specific report. For more information, see [Configuring success criteria for reports](test-config-action.md#test.success-criteria). ## Auto-discovery generates reports that I don't want **Problem:** When I enable auto-discovery, it generates reports that I don't want. For example, CodeCatalyst generates code coverage reports for files included in my application’s dependencies stored in `node_modules`. **Possible fixes:** You can adjust the `ExcludePaths` configuration to exclude unwanted files. For example, to exclude `node_modules`, add `node_modules/**/*`. For more information, see [Include/exclude paths](test-best-practices.md#test.best-include-exclude). ## Auto-discovery generates many small reports for a single test framework **Problem:** When I use certain test and code coverage reporting frameworks, I noticed that auto-discovery generates a large number of reports. For example, when using the [Maven Surefire Plugin](https://maven.apache.org/surefire/maven-surefire-plugin/), auto-discovery produces a different report for each test class. **Possible fixes:** Your framework may be able to aggregate outputs into a single file. For example, if you are using Maven Surefire Plugin, you can use `npx junit-merge` to aggregate the files manually. The full expression may look like this: ``` mvn test; cd test-package-path/surefire-reports && npx junit-merge -d ./ && rm *Test.xml ``` ## Workflows listed under CI/CD don't match those in the source repository **Problem:** The workflows displayed on the **CI/CD**, **Workflows** page do not match those in the `~/.codecatalyst/workflows/` folder in your [source repository](source.md). You may see the following mismatches: + A workflow appears on the **Workflows** page, but a corresponding workflow definition file does not exist in your source repository. + A workflow definition file exists in your source repository, but a corresponding workflow does not appear on the **Workflows** page. + A workflow exists in both the source repository and **Workflows** page, but the two are different. This problem may occur if the **Workflows** page hasn't had time to refresh, or if a workflow quota was exceeded. **Possible fixes:** + Wait. You usually have to wait two or three seconds after a commit to source before you see the change on the **Workflows** page. + If you've exceeded a workflow quota, do one of the following: **Note** To determine whether a workflow quota was exceeded, review [Quotas for workflows in CodeCatalyst](workflows-quotas.md), and cross-check the documented quotas against the workflows in your source repository or on the **Workflows** page. There is no error message to indicate that a quota was exceeded, so you'll have to investigate on your own. + If you've exceeded the **Maximum number of workflows per space** quota, delete some workflows and then perform a test commit against the workflow definition file. An example of a test commit might be to add a space to the file. + If you've exceeded the **Maximum workflow definition file size** quota, change the workflow definition file to reduce its length. + If you've exceeded the **Maximum number of workflow files processed in a single source event** quota, perform several test commits. Modify fewer than the maximum number of workflows in each commit. ## I can't create or update workflows **Problem:** I want create or update a workflow, but I see an error when I try to commit the change. **Possible fixes:** Depending on your role in the project or space, you might not have permissions to push code to source repositories in the project. The YAML files for workflows are stored in repositories. For more information, see [Workflow definition files](workflows-concepts.md#workflows-concepts-workflows-def). The **Space administrator** role, **Project administrator** role, and **Contributor** role all have permission to commit and push code to repositories in a project. If you have the **Contributor** role but cannot create or commit changes to workflow YAML in a specific branch, there might be a branch rule configured for that branch that prevents users with that role from pushing code to that particular branch. Try creating a workflow in a different branch, or commiting your changes to a different branch. For more information, see [Manage allowed actions for a branch with branch rules](source-branches-branch-rules.md). # Troubleshooting problems with issues The following information can help you troubleshoot common problems with issues in CodeCatalyst. **Topics** + [I can't choose an assignee for my issue](#troubleshooting-issues-assignees) ## I can't choose an assignee for my issue **Problem:** When creating an issue, the list of assignees is empty. **Possible fixes:** The list of assignees is directly linked to the CodeCatalyst users listed as members for the project. To verify that user profile access is functioning properly, choose the profile icon and then choose **User profile**. If the user profile information does not populate, check the health report for any incidents. If it does populate, file a service ticket. # Troubleshooting problems with search in CodeCatalyst Consult the following sections to troubleshoot problems related to searching in CodeCatalyst. For more information about workflows, see [Search for code, issues, projects, and users in CodeCatalystSearch for code, issues, projects, and users](search.md). **Topics** + [I can't find a user in my project](#troubleshooting-search-users) + [I don't see what I'm looking for in my project or space](#troubleshooting-missing-results) + [Number of search results keep changing when I navigate through the pages](#troubleshooting-search-results) + [My search query isn't being completed](#troubleshooting-requests-limits) ## I can't find a user in my project **Problem:** When I try to view a user's details, I don't see their information in the project. **Possible fixes:** Search doesn't currently support searching for users within a project. To search for users with access to your space, switch to **This space** in QuickSearch, or remove any project filters you might have specified using the advanced query language. ## I don't see what I'm looking for in my project or space **Problem:** Results don't appear when I try to search for particular information. **Possible fixes:** Content updates are likely to take a few seconds to update in search results. Large updates can take several minutes. For resources that haven't been recently updated, you might need to refine your search. You can refine by adding more keywords or using the advanced query language. For more information about refining your queries, see [Refining your search query](search.md#search-query-language-examples). ## Number of search results keep changing when I navigate through the pages **Problem:** The number of search results appear to change when I go to the next page, so it's not clear how many total results there are. **Possible fixes:** When navigating through pages of search results, you might see a change in the number of search results that match your query. The number of results might update to reflect a more accurate number of matches discovered as you navigate through the pages. As you navigate through the results, you might see the following message: **No results for "test"**. You will receive the message if you don't have access to the remaining results. ## My search query isn't being completed **Problem:** The results of my search query aren't showing up, and it appears to be taking too long. **Possible fixes:** Your search may not be completed when there are many searches being made at the same time in the space, either programmatically or because of high team activity. If you're running programmatic searches, pause or decrease them. Otherwise, try again in a few seconds. # Troubleshooting problems with extensions Consult the following sections to troubleshoot problems related to extensions in CodeCatalyst. For more information about extensions, see [Add functionality to projects with extensions in CodeCatalystAdd functionality to projects with extensions](extensions.md). **Topics** + [I can't see the changes to a linked third-party repositories or search for results of those changes](#troubleshooting-detect-3p-changes) ## I can't see the changes to a linked third-party repositories or search for results of those changes **Problem:** The changes in my third-party reposiory aren't showing up in CodeCatalyst. **Possible fixes:** CodeCatalyst currently doesn't support detecting changes in the default branch for linked repositories. To change the default branch for a linked repository, you must first unlink it from CodeCatalyst, change the default branch, and then link it again. For more information, see [Linking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst](extensions-link.md). # Troubleshooting problems with accounts associated with your space In CodeCatalyst, you can add an AWS account to your space to grant permissions to resources and for billing purposes. The following information can help you troubleshoot common issues with associated accounts in CodeCatalyst. **Topics** + [My AWS account connection request receives an invalid token error](#troubleshooting-connection-token) + [My Amazon CodeCatalyst project workflow fails with an error for the configured account, environment, or IAM role](#connections-troubleshoot-workflow) + [I need an associated account, role, and environment to create a project](#connections-troubleshoot-environment) + [I cannot access the Amazon CodeCatalyst Spaces page in the AWS Management Console](#connections-troubleshoot-console) + [I want a different account as my billing account](#connections-troubleshoot-billing) + [My project workflow fails with a connection name error](#connections-troubleshoot-restriction) ## My AWS account connection request receives an invalid token error **Problem:** When creating a connection request with a connection token, the page does not accept the token and shows an error stating that the token is not valid. **Possible fixes:** Make sure you provide the account ID that you want to add to your space. You must have administrative permissions for your AWS account or be able to work with your administrator to add the account. When you choose to verify the account, a new browser window will open in the AWS Management Console. The same account is required to be logged in on the console side. Try again after verifying the following: + You are logged in to the AWS Management Console with the same AWS account that you want to add to your space. + You are logged in to the AWS Management Console with the Region set to the correct Region for your space. + If you have arrived from the billing page and you want to add the AWS account as a specified billing account for your space, make sure the account has not reached the quota as a billing account for another space or spaces. ## My Amazon CodeCatalyst project workflow fails with an error for the configured account, environment, or IAM role **Problem:** When the workflow runs and does not find a configured account or IAM roles associated with your space, you must fill in the role, connection, and environment fields manually in the workflow YAML. View the failed workflow action, and note whether the error messages are as follows: + The role is not available for use with the connection associated with the environment. + Action did not succeed. Status: FAILED; The provided value for account connection or environment is not valid. Verify the connection is associated with your space and the environment is associated with your project. + Action did not succeed. Status: FAILED; The provided value for IAM role is not valid. Verify the name exists, the IAM role is added to your account connection, and the connection is already associated with your Amazon CodeCatalyst space **Possible fixes:** Make sure that the workflow YAML fields have accurate values for [Environment](build-action-ref.md#build.environment), [Connections](build-action-ref.md#build.environment.connections), and [Role](build-action-ref.md#build.environment.connections.role). The CodeCatalyst workflow actions that require an environment are build or deploy actions that run AWS resources or that generate AWS resource stacks. Choose the failed workflow action block and then choose **Visual**. Choose the **Configuration** tab. If the **Environment**,**Connection name**, and **Role name** fields are not populated, then you will need to manually update the workflow. Use the following steps to edit your workflow YAML: + Expand the `/.codecatalyst` directory, and then expand the `/workflows` directory. Open the workflow YAML file. Make sure that the IAM roles and account information are specified in the YAML that you have configured for your workflow. Example: ``` Actions: cdk_bootstrap: Identifier: action-@v1 Inputs: Sources: - WorkflowSource Environment: Name: Staging Connections: - Name: account-connection Role: build-role ``` The **Environment, Connection, and Role** properties are required to run CodeCatalyst workflow build and deploy actions with AWS resources. For an example, see the CodeCatalyst build action reference YAML parameters for [Environment](build-action-ref.md#build.environment), [Connections](build-action-ref.md#build.environment.connections), and [Role](build-action-ref.md#build.environment.connections.role). + Make sure your space has an account added to it, and make sure that the account has the appropriate IAM role or roles added to the account. You can adjust or add accounts if you have the **Space administrator** role. For more information, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md). ## I need an associated account, role, and environment to create a project **Problem:** In the project creation options, my project either doesn’t have an added account available in my space, or I need another account added to my space for my project to use. **Possible fixes:** For your space, you can add authorized AWS accounts to add them to your project if you have the **Space administrator** role. You must also have an AWS account where you have administrative permissions or can work with your AWS administrator. To make sure an account and role will be available in the project creation screen, you must first add the account and roles. For more information, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md). You have the option to choose to create a service role with a role policy called the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role policy. The role will have a name `CodeCatalystWorkflowDevelopmentRole-spaceName` with a unique identifier appended. For more information about the role and role policy, see [Understanding the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** service role](ipa-iam-roles.md#ipa-iam-roles-service-role). For the steps to create the role, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). The role is added to your account and available in project creation pages in CodeCatalyst. ## I cannot access the Amazon CodeCatalyst Spaces page in the AWS Management Console **Problem:** When I try to access the Amazon CodeCatalyst page in the AWS Management Console to add an account to my CodeCatalyst space or add roles to an account in AWS, I receive a permissions error. **Possible fixes:** For your space, you can add authorized AWS accounts to add them to your project if you have the **Space administrator** role. You must also have an AWS account where you have administrative permissions or can work with your AWS administrator. You must first make sure you are signed in to the AWS Management Console with the same account that you want to manage. After you are signed in to the AWS Management Console, you can open the console and try again. Open the Amazon CodeCatalyst page in the AWS Management Console at [https://us-west-2.console.aws.amazon.com/codecatalyst/home?region=us-west-2\$1/](https://us-west-2.console.aws.amazon.com/codecatalyst/home?region=us-west-2#/). ## I want a different account as my billing account **Problem:** When I set up my CodeCatalyst login, I completed several steps to set up my space and associate an authorized AWS account. Now, I want to authorize a different account for billing. **Possible fixes:** For your space, you can authorize billing accounts if you have the **Space administrator** role. You must also have an AWS account where you have administrative permissions or can work with your AWS administrator. For more information, see [Managing billing](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-billing.html) in the Amazon CodeCatalyst Administrator Guide. ## My project workflow fails with a connection name error **Problem:** When creating a project and then running the project workflow, the workflow fails and shows an error stating that the connection name is not valid, as follows: Failed at : The connection name is not valid. **Possible fixes:** Make sure you provide the account ID that you want to add to your space, and make sure that the account is not enabled for project-restricted account connections. If the account is enabled for project-restricted account connections, then you might need to update the account connection by enabling access to the new project. For more information, see [Configuring project-restricted account connections](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-accounts.html#managing-accounts-restriction). # Troubleshooting problems between Amazon CodeCatalyst and the AWS SDKs or the AWS CLI The following information can help you troubleshoot common issues when working with CodeCatalyst and the AWS CLI or the AWS SDKs. **Topics** + [I receive an error when I enter **aws codecatalyst** at a command line or terminal saying it's an invalid choice](#cli-sdk-troubleshoot-no-commands) + [I receive a credentials error when I run **aws codecatalyst** commands](#cli-sdk-troubleshoot-profile) ## I receive an error when I enter **aws codecatalyst** at a command line or terminal saying it's an invalid choice **Problem:** When I try to use the AWS CLI with CodeCatalyst, one or more of the **aws codecatalyst** commands are not recognized as valid. **Solution:** The most common cause for this problem is that you are using a version of the AWS CLI that does not contain the most recent updates for the latest services and commands. Update your installation of the AWS CLI and then try again. For more information see [Setting up to use the AWS CLI with CodeCatalyst](set-up-cli.md). ## I receive a credentials error when I run **aws codecatalyst** commands **Problem:** When I try to use the AWS CLI with CodeCatalyst, I receive a message stating `You can configure credentials by running "aws configure".` or `Unable to locate authorization token`. **Solution:** You must configure an AWS CLI profile to work with CodeCatalyst commands. For more information see [Setting up to use the AWS CLI with CodeCatalyst](set-up-cli.md).