Skip to main content
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.
If you need a non-browser path, use local-key auth:

​
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: tinycloud onboard for an agent, tc auth login for an OpenKey owner, tc auth login --method local for a local key, or the scoped --paste --manifest login for a secrets 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.
An agent runs tinycloud onboard and sends the owner its link. On a server with no browser, use device login and approve on your phone: tc auth login --device --manifest <file>. See CLI authentication. 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.
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.
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.

​
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 (tc account billing portal --open). 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.
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
These fixes are based on the CLI’s actual error hints and command behavior, not on hypothetical error codes.