# Get help

Copy-paste prompts for common problems, and how to contact COHO support.

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

```text title="Prompt" wrap
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

```text title="Prompt" wrap
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

```text title="Prompt" wrap
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

```text title="Prompt" wrap
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")

```text title="Prompt" wrap
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

```text title="Prompt" wrap
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

```text title="Prompt" wrap
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"

```text title="Prompt" wrap
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"

```text title="Prompt" wrap
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](mailto:support@coho.life)**. Copy this template so we have what we need to help:

```text title="Email to support@coho.life" wrap
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]
```

:::danger[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](../../docs/what-an-atrium-app-is/) has the full technical detail a developer will need.