Troubleshooting

Find the message or code you saw below. Each entry says what it means and what to do next.

A coding app opening and the tool you need being ready are two different things, so check both.

If nothing here resolves it, Contact support at the end of this page lists what to send.

Installing where the home folder is read-only

Some coding agents work on a computer whose home folder can’t be written. The installer checks this before it downloads anything. When the home folder is read-only and it can write to /workspace/shared, it installs csc at /workspace/shared/code-config/bin/csc and keeps all of csc’s files in that code-config folder. When it finds no folder it can write to, it installs nothing and says so:

Could not install in any of these folders: ~/.local/bin, ~/.code-shared-config, /workspace/shared.

Run the install again, naming a folder this account can write to:

curl -fsSL https://dl.code-config.com/install | CODE_CONFIG_INSTALL_DIR=/a/folder/you/can/write sh

csc then lives at /a/folder/you/can/write/code-config/bin/csc. Pick a folder that lasts: a temporary folder such as /tmp gets cleaned, and csc and this computer’s sign-in go with it. To remove this install later, name the same folder:

curl -fsSL https://dl.code-config.com/uninstall | CODE_CONFIG_INSTALL_DIR=/a/folder/you/can/write bash -s -- --yes

When csc can’t add itself to the terminal, the install ends with a line like this:

Run csc by its full path: /a/folder/you/can/write/code-config/bin/csc

Use that full path wherever a command here says csc.

Signing in and connecting a computer

What you see	What to do
Sign-in was denied.	Start again and approve the matching code in the browser.
That code expired. Start again to get a new one.	Start a new connection attempt and approve its new code.
This sign-in is no longer valid. Start again.	The attempt ended before completion. Start again.
This computer is already connected to a workspace.	No new connection is needed. To change workspaces, sign out on that computer first.
Couldn’t reach code-config.com — check your connection.	Check the computer’s internet connection and try again.
The server refused this sign-in. Try again in a moment.	Retry; contact support if the refusal continues.
Sign-in was approved but this computer’s connection wasn’t saved. Try again.	Retry on that computer; approval alone did not finish setup.
The sign-in stopped unexpectedly. Try again.	Start another attempt.
This build can’t reach the network.	Install a supported build from Downloads.
Not reported under a computer’s presence	Nothing has answered for that computer recently. Open the Code Config app there, or run csc listen on a computer with no screen, then read the row again.

This computer couldn’t finish connecting: is followed by the local reason. Use that reason when asking support for help.

Presence and Last sync answer different questions. A quiet computer can still hold the current toolkit, and a computer that answered a moment ago can still be waiting for changes. Read both columns before you reconnect anything.

Connect your computer explains browser approval and remote sign-in.

No toolkit to launch with

What you see	What it means	What to do
No toolkit yet. Create one to start launching.	The workspace has no toolkit to select.	Create or adopt a toolkit, then choose it.
This toolkit isn’t on this computer yet.	The selected toolkit has not reached this computer.	Run csc sync, then try again.
This workspace has no toolkits. The project is still mapped; launching remains unavailable until one exists.	The project connection exists, but there is no toolkit.	Create or adopt a toolkit. You do not need to reconnect the project.

For an unexpected toolkit, check Toolkit selection order.

The coding app didn’t start

What you see	What to do
Not installed on this computer.	Install the coding app on the selected computer, then retry.
This app is not available on this system.	Choose a supported app or supported form of that app.
This launch target has no compatible adapter.	Choose another supported launch target.
Couldn’t be started on this computer.	Retry once; if it repeats, send support the message and client version.

For web request states such as Not picked up or Launch status unknown, use Launch from the web app. Check an existing request before sending another.

Reading a launch’s notes and codes

Action needed means the coding app needs your approval before some content takes effect. Notes on this launch describes other issues, such as an unsupported tool, a conversion limit, missing content, or a server needing setup.

Neither heading alone tells you whether the whole toolkit is usable. Read the affected item and reason, then check the tool in the coding app. An empty diagnostics array means Code Config reported no diagnostics, not that every external service has been tested.

With JSON output, launch diagnostics are in the diagnostics array. Use the app’s launch command with --json; the command-line reference explains where to find its exact syntax.

Add --strict and the launch command exits with a non-zero code whenever the configuration is not fully in place, and names each thing you still need to do. Six codes never make it fail, because each one describes a result you can use: item_placed_with_losses, item_replaced_by_same_name, host_requires_user_action, mcp_server_in_session, launch_notes_not_recorded, and sign_in_first. Every other code below does.

Launch codes

Code	What it means	What to do
toolkit_manifest_not_cached	The toolkit content was not available in this computer’s cache.	Sync, then launch again.
host_has_no_materialized_row	No prepared toolkit content was available for the coding app.	Check app compatibility, sync, then retry.
toolkit_receipt_write_failed	Code Config could not save its record of the files written.	Check home-folder permissions, then retry.
launch_notes_not_recorded	Everything this launch set up is in place; Code Config could not save its own notes about it.	Nothing to do. Check home-folder permissions if it keeps happening.
item_content_unavailable	Repository content could not be fetched.	Check network and source access, then retry.
item_content_plan_rejected	The proposed files were rejected before writing.	Review the named toolkit items and reason.
item_content_write_failed	Writing repository content did not complete.	Check disk space and folder permissions. Not all tools were installed.
project_sync_failed	The project folder’s settings for your app, or the folder for any agent, were not updated. The message says why when Code Config can tell.	When the message names a step, such as signing in to GitHub, closing a program that has a file open, or moving a file of yours out of the way, take it and run the same command again. Otherwise check folder permissions and run setup again.
item_not_placed	The coding app cannot use one named item.	Read that item’s compatibility result; choose another app if needed.
item_placed_with_losses	A conversion omitted unsupported details.	Read the named loss before relying on the converted tool.
item_replaced_by_same_name	Two tools in your toolkit have the same name, so the launch used the one later in your toolkit and left the other out.	Nothing to do. To use the other one, take the kept one out of your toolkit.
item_moved_or_renamed	Code Config could not get one of your tools from where it comes from, so the launch was set up without it.	Set that tool up in this project by hand, or take it out of your toolkit.
toolkit_setting_not_applied	One of your toolkit’s settings did not reach the coding app: your toolkit’s extra settings are not written in a form the app reads, or two settings files in your toolkit set the same setting.	Fix the text the message names, or take the setting out of one of the two files, then launch again.
app_data_not_fully_seeded	Some of your saved app data could not be copied into this session.	The app may ask you to sign in again. Sign in there and carry on.
sign_in_first	The coding app has no saved sign-in for this account yet, so it opens on its own sign-in screen first.	Sign in there, then come back and launch again to open your project.
toolkit_env_setup_required	The app started without one of your toolkit’s settings.	Run the setup command in the result, then launch again.
mcp_server_not_in_session	A server in your toolkit was not set up in the coding app: it is not set up to start yet, its name cannot be used, its name is already taken by another server, or the CLI could not be found.	Follow the named reason: finish setting that server up, rename it, or install the CLI.
mcp_server_in_session	A server your toolkit carries is set up in the coding app.	Nothing to do.
mcp_server_not_registered	A server in your toolkit was not added to the coding app. The message names the server and why.	Find that reason under An MCP server is not ready and do what it says.
mcp_not_registered	A server was left out for a reason other than a missing key, such as a name another server already has, a program that is not installed, or a connection the coding app does not support.	Find the server’s state under An MCP server is not ready and do what it says. This code carries no setup command.
no_mcp_servers_registered	No tool servers were added for this launch. Your toolkit has tool servers, the coding app got none of them, and no server’s own message says why; its other tools may still be in place. When a server’s message says why, you get that message instead of this one.	Launch again.
mcp_setup_required	A server still needs local setup.	Run the exact setup command in the result, then check the server.
host_requires_user_action	The coding app needs your approval for delivered content.	Review and answer its prompt in the coding app.

When a launch cannot report on itself

runtimeReporting is included when launch reporting is degraded. This is separate from toolkit delivery and the coding app’s state.

Code	Meaning and next action
lock_unavailable	Another process holds the reporting lock. Let that operation finish.
journal_unavailable	The local reporting record could not be opened. Check permissions on Code Config’s local files.
delivery_pending	A report is queued locally. Check connectivity if it remains pending.
worker_unavailable	The reporting worker is not running. A later launch retries reporting; contact support if it persists.

An MCP server is not ready

Copy the exact setup command from the launch result, or from the server’s details on the toolkit’s Contents in the web app. The command identifies the toolkit and server for you.

A launch leaves a server out rather than fail. The launch answer lists it under mcpServers with a state word and a detail sentence. Only needs_value carries a setup command, in next.

State	What it means and what to do
needs_value	The key is not on this computer yet. Run the row’s next, or paste the key under Settings → Keys in the Code Config app, then launch again.
unreachable	The key is kept in a store this computer cannot read right now. Unlock or restore access to that store, then launch again.
key-is-placeholder	What is saved for the key is a placeholder, not the key. Save the real key with the server’s csc key set command, then launch again.
keys-not-loaded	This computer’s saved keys could not be loaded. Check permissions on Code Config’s local files, then launch again.
toolkit-copy-out-of-date	This computer’s copy of the toolkit is behind. Check the internet connection and launch again; a launch gets your newest toolkits first.
server-kind-not-startable	The server comes in a form this computer cannot start. Choose another server for that service, or take this one out of the toolkit.
program-not-found	The server’s program is not on this computer yet. Launch again; a launch installs a missing program itself.
program-not-installed	The launch could not install the server’s program. Run csc setup run --toolkit <toolkit-id>, which installs it and says why when it cannot, then launch again.
program-folder-others-can-change	The program sits under a folder that other people on this computer can change, and detail names that folder. Make the folder writable only by you, for example chmod go-w <folder>, then launch again.
program-not-verified	The program on this computer is not the one the server asks for, so it is not started. Contact support with the message.
program-changed-since-set-up	The server’s program has changed on this computer since it was installed, so it is not started. Contact support with the message.
program-set-up-twice	This computer has more than one program saved for this server and cannot tell which to start. Contact support with the message.
program-set-up-twice-in-toolkit	This toolkit has more than one program saved for this server and cannot tell which to start. Contact support with the message.
program-record-unreadable	Code Config’s note about which program to start could not be read. Contact support with the message.
name-already-taken	Another server in this launch has the same name, so only one of them is set up. Take one of them out of the toolkit.
name-not-usable	The coding app cannot use the server’s name. Choose another server, or open the toolkit in another coding app.
transport-not-supported-by-app	The coding app does not support the way this server connects. Open the toolkit in another coding app.
value-not-writable-here	One of the server’s settings holds text this coding app would rewrite before using it. Open the toolkit in another coding app.
key-would-be-shared	The server needs a key, and this coding app reads it from a project file that everyone with the project gets. Open the toolkit in another coding app.
app-settings-unreadable	The coding app’s own saved settings on this computer could not be read, and Code Config leaves that file as it is. Fix or reset the coding app’s settings, then launch again.

Run the provided setup command after resolving the named prerequisite. An unlock prompt or permission decision still needs your action; repeating setup is not a substitute for that action.

When the coding app starts the server

The coding app starts each MCP server itself, from the configuration the launch wrote for it, so a server that fails after the app has opened reports the failure in the app rather than in the launch result. A service that rejects the credential and a server program that is not installed both show up there.

Run csc key get –toolkit <toolkit-id> on that computer and use the state in the table above. If setup reports the server ready and the coding app still cannot start it, run the toolkit’s setup command with the corrected credential and launch again. The new value reaches the coding app with the next launch.

csc key set refusals

When csc key set cannot save a value, it says why in plain words. Run csc key get --toolkit <toolkit-id> to see the toolkit’s servers, apps, and setting names as the command expects them.

Set up MCP credentials explains supported inputs, scopes, and storage.

Exit codes

Management commands use these outcomes for scripts and JSON output. Other command families also have their own help; check both their exit status and returned details.

Exit	Kind	Meaning and next action
0	—	The command succeeded. Read any item-level diagnostics as well.
1	internal_error	Retry; contact support if it persists.
2	invalid_request	Check the command’s arguments and options.
3	not_authorized	Check the account, computer connection, and required permissions.
4	conflict	The object exists or changed. Refresh its state before retrying a write.
5	action_required	Complete the action named in the response.
6	temporarily_unavailable	Check connectivity and retry later.
7	not_found	The toolkit, change, or other thing named does not exist. Check the name or id.
10	upgrade_required	Install a current supported build.

Contact support

Email hello@code-config.com when the steps above do not get you moving again. Include:

• what you were trying to do, and what happened instead;
• the coding app and the Code Config version you are on;
• the exact message or code you saw, copied rather than described;
• whether the coding app opened at all, and the name of the computer you were on.

Leave key and token values out of the message; nobody needs them to read the error with you. Help & Feedback in the web app has the same email button, next to prompts you can paste into your coding agent.