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 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.