Troubleshooting
Find the next action when installation, sign-in, collection, or scores go wrong.
Start with the symptom you see, and keep four things apart: installation, sign-in, collection, and analysis delay. prism status is the first check for all of them. Commands shows the full output.
Installation
Section titled “Installation”prism is not found
Section titled “prism is not found”- Open a new terminal window and run
prism status. - If the shell still does not find
prism, run the install command from the Install guide screen again. Open Connect in the header to reach it.
prism setup says Claude Code or Codex was not found
Section titled “prism setup says Claude Code or Codex was not found”If you record every session, prism setup looks for the two tools separately. It prints Claude Code was not found (no configuration directory and no `claude` on PATH); skipped. when it finds neither Claude Code’s configuration directory nor a claude program on your PATH, and Codex was not found (no configuration directory and no `codex` on PATH); skipped. for Codex. Hooks are registered for the tool it found, so check only the line of the tool you use.
- Check that
~/.claudeor~/.codexexists, or thatclaude --versionorcodex --versionworks in the same terminal. - If the configuration lives elsewhere, set
CLAUDE_CONFIG_DIRorCODEX_HOMEto that directory and runprism setupagain.
prism setup fails on the settings file
Section titled “prism setup fails on the settings file”the settings file is not valid JSON or the settings file is not a JSON object means Claude Code’s settings file cannot be edited safely. Fix the file, then run prism setup again. Do not delete the whole settings file to reset Prism. prism setup changes only its own entries.
prism status shows the hooks as not registered
Section titled “prism status shows the hooks as not registered”Claude Code hooks: not registered (<path>) or Codex hooks: not registered (<path>) means the settings file at that path has no Prism hooks. Run prism setup. If the path is not the file your tool reads, check CLAUDE_CONFIG_DIR or CODEX_HOME. If Codex trust: does not say approved, approve the Prism hooks when Codex asks; nothing is collected from Codex until you do.
An update did not take effect
Section titled “An update did not take effect”Run prism status and read Upgrade needed. If it says yes, the server needs prism <version> or newer or yes, the server refused the last send, update prism, install the newer version as described in Install and update and run any prism command. The prism <version> line then shows the new version.
Sign-in
Section titled “Sign-in”prism login does not finish
Section titled “prism login does not finish”- Check that the code on the Approve device screen matches the one in the terminal. The code is valid for 10 minutes. After
The login code expired., runprism loginagain. - If the screen says only accounts with a confirmed email address can approve devices, confirm your address with the mail you received at sign-up, then run
prism loginagain. Could not reach <server>points to the network or the address. If the Install guide screen shows the sign-in command with--server <address>, copy that command so the CLI reaches the right service.
prism status says you must sign in again
Section titled “prism status says you must sign in again”These lines mean the server no longer accepts this device’s sign-in:
Login: login expired, run `prism login`withToken: refused by the serverLogin: login required, run `prism login`withToken: valid, but the server refused the last sendConnection: the server refused the loginConnection: reached <server>, login required
Run prism login. Look in Settings → Devices first if you expect the device to still be active: a device shown as Logged out was signed out on purpose, from there or with prism logout.
prism status cannot check the sign-in
Section titled “prism status cannot check the sign-in”Login: not logged in, run `prism login`andToken: none: no token is stored. Runprism login.Login: could not be checked, the stored login cannot be read: the Keychain or the token file could not be read. Runprism loginagain.Token: not checked, a send is running: a background send was using the token. Runprism statusagain in a moment.Token: could not be checked (...)andConnection: could not reach <server>: the service did not answer. Check your network, then runprism statusagain.
Collection
Section titled “Collection”No activity appears in the web app
Section titled “No activity appears in the web app”Work through these checks in order and stop at the first one that fails.
- Signed in?
prism statusmust showLogin: logged in. If not, see Sign-in above. - Hooks registered? If you record every session with the CLI,
Claude Code hooks: registered in <path>orCodex hooks: registered in <path>must appear for each tool you use. If not, runprism setup. If you start sessions withprism claudeorprism codex, the hooks stay unregistered and this check does not apply. If you use a plugin, run/prism:statusor$prism:statusinstead:Loginmust saylogged in, and for Codex you must have trusted the 4 hooks in/hooks. - A new session? Sessions started after the sign-in and, for every-session recording, after
prism setupare recorded. A session that was already open is not. Open a new session, enter a prompt, and let the agent finish its turn. - Collection switched off?
PRISM_OFF=1in the environment of Claude Code or Codex silences the hooks. Runecho $PRISM_OFFin the terminal you start the tool from, and check your shell profile. - Did a hook fire?
Last trigger: none yetmeans no hook has recorded anything. If a time is shown, the hooks work; continue below. - Did a send succeed?
Last successful send: never, orUnsent envelopesgrowing, means sending fails. ReadLast errorandConnection. If the connection line is notok, check your network, proxy, and the service address. - Skipped sessions?
Skipped sessions (last 7 days): <n> (<reason>)lists sessions that the CLI did not send.session_id_too_longmeans the session’s identifier exceeds 512 bytes, which the server refuses. Such a session stays on your Mac and is not retried. - Right context?
New sessions are collected undershowsPersonalor an organization. Check that the screen you look at matches it.
Collection can be delayed or incomplete. The CLI keeps unsent records for at most 14 days and 256 MiB. It writes a note about dropped records and skipped sessions to flush.log in the Prism folder (~/.config/optra-prism on macOS; ids and counts only, never text). Reinstalling does not recover records that were already dropped.
Unclassified records
Section titled “Unclassified records”Unclassified records (last 7 days): <n> unknown, <m> ignored in <k> sessions counts records in the session files of Claude Code and Codex that the CLI did not classify. The counts stay on your Mac. Include this line when you ask for help.
Analysis delay
Section titled “Analysis delay”Activity appears but a score does not
Section titled “Activity appears but a score does not”Prism evaluates a stretch of work after it closes: at the end of the session, after /clear, or three hours after the last activity. The first result after your first prompt can therefore take up to three hours if you keep the session open. Open the activity in Realtime or Sessions and read its status. See Scores and work status and Periods and data states.
Do not change a legitimate task just to obtain a score.
Prepare a support report
Section titled “Prepare a support report”Include the symptom, the output of prism status (or of /prism:status or $prism:status for a plugin), your operating system, the tool you use (Claude Code or Codex) and its version, how you installed Prism (the CLI or a plugin), and the time and time zone of the missing activity. Remove private text from anything you paste. Open Support in the web app to contact the team.