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

# Troubleshooting

> Fix common TinyCloud CLI, hosting, and OpenKey problems

Use this page to map a symptom to the next command or config check.

## No profile, key, or session

**Symptom:** `tc doctor` reports a missing profile, missing key, or missing session.

**Fix:** Start with profile setup and sign in.

```bash theme={null}
tc init
tc auth login
```

If you need a non-browser path, use local-key auth:

```bash theme={null}
tc auth login --method local
```

## Session expired or sign-in required

**Symptom:** `tc context --json` shows `"state": "expired"`, or a command fails
with `AUTH_REQUIRED` (exit `3`; every command in CLI 1.1.0 beta, headless
`tc secrets` commands in 1.0.0).

**Fix:** sign in again the same way the profile was created: `tc auth login`
for an OpenKey owner, `tc auth login --method local` for a local key, or the
scoped `--paste --manifest` login for an agent profile. Device logins can be
renewed with the same `--device --manifest` command.

If a login fails with `SESSION_IN_USE`, the new request would narrow or
shorten a session the profile already holds. Use a new profile for the new
purpose, or pass `--replace-session` if you mean to replace it.

## Browser auth did not open

**Symptom:** `tc auth login` cannot open a browser callback.

**Fix:** Use paste mode or suppress the popup.

```bash theme={null}
tc auth login --paste
tc auth login --no-popup
```

On a server or in an agent with no browser, use device login and approve on
your phone: `tc auth login --device --manifest <file>`. See
[CLI authentication](/cli/authentication#device-login-for-agents-and-servers).

If you are pointing at a self-hosted OpenKey instance, verify `TC_OPENKEY_HOST` or the profile's `openkeyHost`.

## Node health check fails

**Symptom:** `tc node health` says the node is unreachable.

**Fix:** Confirm the host and check the health endpoint.

```bash theme={null}
tc node health
curl http://localhost:8000/healthz
```

If you changed the node URL, check `TC_HOST` and the profile's `host` value.

## `tc doctor` and `tc node health` disagree

**Symptom:** `tc doctor` reports the node as unreachable, but `tc node health`
or a direct `/healthz` request succeeds.

**Cause:** The current CLI commands probe different paths: `tc doctor` checks
the legacy `/health` path, while `tc node health` checks the node's implemented
`/healthz` endpoint.

**Fix:** Use `tc node health` or `/healthz` as the node-health check and treat
the `tc doctor` node result as CLI drift. Continue using `tc doctor` for its
local profile, key, session, and space checks.

## Space is not hosted

**Symptom:** `tc kv` or `tc sql` reports that the target space is not hosted.

**Fix:** Host the owned space before retrying the data command.

```bash theme={null}
tc space create applications
tc space create secrets
```

Use `tc space info` or `tc space list` to confirm the resolved space URI.

## Secrets network is missing

**Symptom:** `tc secrets doctor` reports that the encryption network does not exist.

**Fix:** Create or reuse the default network.

```bash theme={null}
tc secrets network init
tc secrets network show
```

## Storage is full

**Symptom:** a write fails with `STORAGE_QUOTA_EXCEEDED`, or with
`STORAGE_LIMIT_REACHED` when one write is larger than the space left.

**What still works:** reads. Nothing from the refused write was saved, so the
space is unchanged.

**Fix:** do not retry the write. Free up space or upgrade the plan at
[account.tinycloud.xyz/billing](https://account.tinycloud.xyz/billing)
(`tc account billing portal --open`).

| Surface | What you see |
| - | - |
| CLI 1.0.0 | `tc kv put` exits `1`; `tc share publish` exits `4` |
| CLI 1.1.0 beta | Every command exits `10`: `TinyCloud storage is full; nothing was written.` |
| SDK | A failed `Result` with `error.code` `STORAGE_QUOTA_EXCEEDED` or `STORAGE_LIMIT_REACHED`; `meta.usedBytes` and `meta.limitBytes` when the node reports them |
| MCP 0.4.0 beta | `STORAGE_QUOTA_EXCEEDED` with `retryable: false` |

In apps, treat this as a read-only state rather than an outage: keep showing
the user's data and disable writes. SDK 3.1.0 beta adds
`isStorageFullError(error)` to test for both codes, and reports them from SQL
and DuckDB writes too.

## A permission request is waiting

**Symptom:** You created a request artifact, but the action still fails.

**Fix:** Inspect local state and retry once the requested capabilities are covered.

```bash theme={null}
tc status
tc auth caps
tc auth retry --last
```

If a request still is not covered, grant or import the matching delegation artifact first.

## Where to look next

* `tc doctor` for a quick local diagnostic pass
* `tc status` for local profile and permission state
* `tc auth caps` for coverage details
* `tc secrets doctor` for secrets-specific checks

<Note>
  These fixes are based on the CLI's actual error hints and command behavior, not on hypothetical error codes.
</Note>


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