Get help

Most problems can be fixed by your AI once it knows what to look for. Find your problem below and copy the prompt. Each one points your AI at the part of the spec that explains it.

My app failed to build

Prompt

My COHO hosted app failed to build (provisioning state: failed). Find out why from the
COHO MCP tools or the Store, then check the zip: it must include a Dockerfile, the
Dockerfile path I gave must be right, dependency files the Dockerfile needs (such as a
lockfile) must be included, and the app must listen on the port in the PORT environment
variable. Fix what's wrong, then update the hosted app with a new zip (show me the preview first).

Connecting in the Store fails

Prompt

Connecting my Atrium app in the COHO Store fails and rolls back. Check my setup handler
against section 3.2 of the spec: it must read the bootstrap secret from ATRIUM_SETUP_SECRET
(COHO provides this value; on COHO Hosting it's injected automatically, so never hard-code
or invent one), verify lifecycle.setup with it before storing anything, never use
data.signingSecret to check setup, save the apiKey and signingSecret against the connection
reference, and return HTTP 2xx. A 404 or any other error on setup makes the connect fail.

My app shows as degraded or paused

Prompt

The COHO Store shows my Atrium app as degraded or paused. Check the health check against
section 4 of the spec: GET /health must return 2xx with an empty body or {"ok": true}.
After three failed checks in a row COHO pauses events and schedules until one succeeds.
Find out why it's failing and fix it.

Events or schedules never arrive

Prompt

My Atrium app isn't receiving events or schedules from COHO. Check: is the app healthy
(section 4)? Does it reply with HTTP 2xx quickly and do slow work afterwards (section 3.1)?
Does signature verification pass (section 3.1.1 test vectors)? Is it handling the right
event key (section 3.4)? Use Run test in the Store to send a test event, then check the logs.

Messages from COHO are rejected (“signature doesn’t match”)

Prompt

My Atrium app rejects COHO's signed messages. Check the verifier against section 3.1 of
the spec: sign the raw body bytes exactly as received (don't re-serialise JSON), include
method, path-and-query and connection reference, compare in constant time, and allow the
timestamp window (30s future, 300s past). Prove it passes all three test vectors in 3.1.1.

My panel is blank or won’t open

Prompt

My Atrium app's panel (quick view) is blank or won't load inside COHO. Check section 6 of
the spec: the Content-Security-Policy frame-ancestors header must list COHO's origins
(not *), and the signed launch URL must be verified like other signed GETs. For a hosted
app with a browser UI, check config.browserBaseUrl in the manifest.

The settings form doesn’t show or save

Prompt

My app's settings form in the COHO Store doesn't load or save. Check the light config
routes against section 5.3 of the spec: GET schema, GET values and PUT values, all signed
with the connection signing secret, and the schema must follow section 5.3.1.

COHO’s API says “403 Forbidden”

Prompt

My Atrium app gets HTTP 403 from the COHO Public API. Check section 8 of the spec: is the
capability declared in requestedCapabilities? High-risk areas (for example conversations
or rentPayments) need a manager to approve them in the Store. Tell me which capability is
missing and what I need to ask a manager to approve.

COHO’s API says “429 Too Many Requests”

Prompt

My Atrium app gets HTTP 429 from the COHO Public API. The limit is 100 requests a minute
(section 7 of the spec). Add retries with backoff and reduce how often the app calls the API.

Still stuck? Email COHO support

Email support@coho.life. Copy this template so we have what we need to help:

Email to support@coho.life

Subject: Atrium app help: [app name]

Organisation: [your COHO organisation name]
App name: [app name]
Hosted by COHO or self-hosted: [hosted / self-hosted]
Provisioning state (if hosted): [e.g. ready / failed]
AI tool used: [e.g. Cursor, Claude Code]

What I'm trying to do:
[one or two sentences]

What happens instead:
[what you see, including any error message or Store log entry]

What I've tried:
[the prompts or fixes you've tried]

Never send secrets

Don’t include your app’s API key, signing secret or setup secret in an email, chat or support request.

When to bring in a developer

AI tools can get you a long way, but bring in a developer when:

• you want to list your app publicly in the COHO Store. Public listings must pass a quality check first.
• your app handles sensitive data or high-risk areas, such as messaging tenants or rent payments.
• it needs to work with your other systems, beyond COHO.
• you’re stuck in a loop, where your AI keeps making the same fix and it keeps failing.

The developer guide has the full technical detail a developer will need.