Troubleshooting

Symptoms, causes and fixes for the problems people actually hit — access, gates, assignment, keys, webhooks and agents.

A colleague signed up and cannot see our projects

They created their own workspace instead of joining yours. Workspaces cannot be merged. Have an admin invite them from Team, and have them join through the invite link with the address it was sent to. The empty workspace can simply be abandoned.

The invite email has not arrived

Check spam, and check the address for typos — invites go to the exact address entered. If your team is on the free plan and already has five members, the invite is refused with a limit message; upgrade or remove a member first.

Use Forgot password on the login page. If the account was created with Google, there is no cadence. password — sign in with Google instead.

Phases and gates

The "Complete phase" button is disabled

At least one criterion is still incomplete. Hover the button: it lists every criterion blocking the gate. Either meet them, or mark the ones met-with-caveats as conditionally passed. See gate criteria.

The next phase did not start

The next phase starts automatically only when the previous one is completed through the gate. If a phase's status was set directly — by hand, or through PATCH /phases/:id — no progression happens. Complete the phase properly, or set the next phase's status yourself.

A phase completed without checking anything

It had no criteria. A phase with an empty gate completes freely. Add criteria to the phase, and to the template it came from so the next project inherits them.

Tasks and assignment

Automatic allocation assigned everything to one person, or spread it randomly

Allocation matches the skills a task requires against the skills people have. If either side is empty it has nothing to match on and simply distributes the work.

Fix both sides: add skills to people on their profiles, and to tasks — ideally in the template, so every future project starts with them.

Allocation skipped some tasks

By design. It only touches tasks that are both unassigned and not started, so it never pulls work away from someone who has already picked it up.

I cannot assign someone to a task

They are not on the project team. Add them to the project first, from the project page.

Portfolio dashboards

The blockers panel is empty but things are clearly stuck

The panel reads the blocked task status. If people leave stalled work as in progress, nothing shows. This is a habit problem, not a settings problem — set the status to blocked, and leave a comment saying what it is waiting on.

Workload charts look wrong

They are computed from estimated hours. Tasks without estimates contribute nothing, so a team with sparse estimates looks under-loaded. See managing tasks.

A project is missing from a tag dashboard

It does not carry that tag. Open the project and add it — tags are per project and are not inherited from anything.

API

`401 Missing or invalid API key`

The header is absent or malformed. It must be exactly Authorization: Bearer cad_live_…. A common cause is an environment variable that lost its value in deployment, leaving Bearer undefined.

`401 Invalid API key`

The key does not match any on record — usually a truncated copy. Keys are shown only once at creation; if you are not certain you have the whole string, revoke it and create another.

`403 API access requires a Pro or Enterprise plan`

The key is fine; the team is on the free plan.

`404` on a resource you know exists

Either the id is wrong, or it belongs to a different workspace. The API returns 404 rather than 403 across workspace boundaries on purpose. Confirm which workspace your key belongs to with GET /users/me.

`429 Rate limit exceeded`

You have passed 1,000 requests per minute on Pro, or 5,000 on Enterprise, counted per team across REST and MCP together. Back off until the window rolls over, and batch reads — GET /projects/:id returns phases and tasks in a single call.

Webhooks

Nothing is arriving

Work through, in order:

Is the endpoint is_active? Check GET /webhooks.
Is it subscribed to the event you expect? Endpoints only receive events they registered for.
Is your URL reachable from the public internet, and does it respond within 10 seconds?
Check the delivery log — every attempt records its status code and the start of your response body.

Signature verification always fails

Almost always because the HMAC is computed over re-serialised JSON. Sign the raw body bytes, exactly as received, before any parsing. See verifying the signature.

An event was missed

Deliveries are not retried after a failure. If your system cannot miss changes, reconcile periodically against the REST API.

Agents

Test connection fails

cadence. connects to your agent's MCP endpoint and issues a trivial call, so the endpoint must be reachable and must expose an execute_sql tool. The error message returns the underlying failure — start there. If the endpoint needs a token, set mcpAuthToken on the agent.