Setup didn't finish

Symptom

You see a “Setup didn’t finish” message when opening a repository, with a Retry button.

Cause

The setup agent session ended before completing all required steps. Common reasons:

• The terminal session was closed or crashed mid-setup
• A network interruption broke the connection to your issue tracker
• The agent encountered an error it couldn’t recover from (for example, API rate limiting or a permissions error)

Fix

Try retrying first

Click Retry. The setup agent resumes and can often pick up where it left off by detecting what’s already been created.

Check what was created

If retry doesn’t work, check the .cate/ directory in your repository to understand how far setup got:

• No .cate/ directory — setup failed very early. Retry should work.
• .cate/workflows.json exists but .cate/guardrails/ is empty — setup completed the configuration step but stopped before guardrails. Retry should pick up at the guardrails step.
• .cate/workflows.json exists and guardrails are defined — setup may have completed but the completion signal was lost. Try opening the repository again.

Start fresh

If the .cate/ directory is in a broken state, delete it and retry:

rm -rf .cate/

Then open the repository in Cate again. Setup starts from scratch.

Check your credentials

If setup fails repeatedly during board creation or status column configuration, the issue is likely expired or under-scoped credentials. See Credentials.