> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcliq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting hugs

> What each hug error means and what to do about it.

Hugs

## Asking

| Error | Where | Meaning | What to do |
| - | - | - | - |
| `TEAM_HUG_UNKNOWN` (422) | `cliq team install`, CliqHub installs | A phase asks with a hug this daemon can't find — like an agent that isn't set up, the team isn't installed | `cliq hug list` shows what it finds. Build the team's hug (`hugs/<name>/dist/`), or put it on `CLIQ_HUGS_PATH`, then install again |
| `hug_unknown` / `HUG_UNKNOWN` | the pre-run check (every run, CliqHub's and sub-teams' too), `ctx.ask`, an LLM phase | A phase's `hug.name` (or `ctx.ask('name')`) matches no hug on this daemon | `cliq hug list` shows what it finds. Build the team's hug (`hugs/<name>/dist/`), or put it on `CLIQ_HUGS_PATH` |
| `HugRefusedError` | `ctx.ask` | The params don't match the definition, the shape is from before hugs, or cliqd or CliqHub refused the Hug (an unknown channel, nobody who can answer) | The message says which. For the old shape, see [Migrating](https://docs.getcliq.io/hugs/migrating.md) |
| `INVALID_HUG` | a CLI agent | The model's `cliq_hug` block doesn't fit the phase's hug | Make the role say what to ask; check the hug's `description` |
| `invalid_hug` (422) | CliqHub | An envelope CliqHub refuses — for example `template` from a cliq older than hugs | Update cliq |
| `BUNDLE_MISSING` (409) | CliqHub → cliqd | CliqHub doesn't have this bundle yet | Nothing — cliqd sends it and opens the Hug again. If it persists, cliqd couldn't read the hug's `dist/` |
| `BUNDLE_INVALID` (422) | CliqHub | The bundle breaks a rule: binary files, over 5 MB or 200 files, no `hug.json` or `definition.mjs`, or its hash doesn't match | `cliq hug build` reports the same rules locally |
| `BUNDLE_REJECTED` (403) | CliqHub | A bundle sent by something other than a daemon of the Hug's realm | Bundles come only from the realm's daemons |

## Building

`cliq hug build` names the file and the rule it breaks: a binary file (inline it — the build inlines assets by
default), an outside URL, too many files or bytes, a missing `hug.json` or `definition.mjs`. `cliq team publish`
refuses a team hug whose `dist/` is out of date — `cliq hug build hugs/<name>`, or publish with `--build`.

## On the page

Errors a page's code can see (`HugError`, with a `code`):

| Code | Meaning |
| - | - |
| `not_in_runtime` | The page was opened outside a Hug host — use `cliq hug dev` |
| `protocol_unsupported` | The host and the page share no protocol version — rebuild the hug with a current SDK |
| `timeout` | The host didn't answer in time |
| `upload_cancelled` | The person closed the file picker |
| `upload_failed`, `read_failed` | The upload or read failed — try again |
| `not_declared` | An upload for a key the Hug has no slot for — add it to the definition (`file()`) |
| `file_too_large`, `file_type` | The file breaks the slot's `max_bytes` or `accept` |
| `read_denied` | The viewer may not read that file |
| `rate_limited` | Too many messages, uploads or reads at once |

**An answer isn't accepted:** the agent checks every answer with the definition. One that fails isn't counted — the
run's log says why ("the answer from Ann couldn't be used — …"), and the page shows "1 answer couldn't be used;
waiting for a valid one". The page and the agent use the same definition, so this usually means the answer didn't come
through the page (a script, an older bundle).

**The page is blank:** open the browser's console on the Hug page. A page that loads anything from outside its bundle
is blocked by its Content Security Policy; `cliq hug dev` reports the same.

## Answering without a browser

Scripts, CI and tests answer a local Hug with cliqd's API, with the values the hug expects:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl -s -X POST http://127.0.0.1:4900/v1/hugs/respond -H 'content-type: application/json' \
  -d '{"hug_id":"<id>","values":{"decision":"approve","comment":"LGTM"},"summary":"Approved","responder":"ci"}'
```

The answer is checked like any other.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.