Troubleshooting

Start with jevlin status, jevlin agents status and jevlin doctor. Between them they say what this installation has, what each agent has, and what is not working, with the one thing to fix. This page goes symptom by symptom.

jevlin status          # what this installation has and has not completed
jevlin agents status   # which agents are set up, and how each was found
jevlin doctor          # whether searches are recorded and earning, check by check

Both status and doctor take -json. See Doctor's checks.

A search does not run

The agent does not know about Jevlin. Run jevlin agents status. An agent that is not listed as installed gets jevlin agents install -client <id>. Restart any agent that was already open when setup ran; the skill and hooks load at the next start.

The agent asks for approval on every search. The hooks allow exactly the search command the skill renders. A search spelled differently, such as one after a cd or inside a loop, waits for approval. On Windows, a search through Claude Code's PowerShell tool asks every time and runs when you approve; searches through the Bash tool are covered. See Claude Code.

Codex runs searches but records nothing, and the trace has no session. Codex runs Jevlin's hooks only after you approve them. Start codex, or open the app, and approve them when it asks you to review hooks. jevlin agents status says what Codex has on record. Codex must be 0.158.0 or newer. See Codex.

Codex searches on Linux are recorded but never delivered. Codex's Linux sandbox ends the flush a search starts, so the evidence waits for a Jevlin run outside Codex. Approve Jevlin's SessionStart and Stop hooks in Codex; until then jevlin status counts the searches waiting and when the oldest was made (delivery in status -json), and jevlin agents status says which hooks lack an approval. A jevlin flush from your own shell delivers them now. macOS is not affected. See Codex.

The command is not found. Say yes to the shell profile question, or add the block by hand. Open a new shell afterwards.

jevlin setup            # answer yes to "Add them to ~/.zshrc?"

A search fails with action: connect or action: login. connect means the registration, setup or claim needs attention: run jevlin connect. login means the search credential exists and was not accepted: run jevlin login. The two are different, and the envelope says which. See the envelope.

doctor says UNKNOWN

UNKNOWN is the absence of a fact, never a polite NO. doctor exits non-zero only when every check came back UNKNOWN.

recording UNKNOWN with "recent miner activity, but nothing is queued locally or verified at the AS" means something ran, yet no search was recorded: usually an agent using a different config, or a sandbox that cannot write the intake directory. Check jevlin agents status and re-run jevlin agents install. recording never says NO; could not determine gives its reason and is not a fault either.

intake writable could not determine means neither the intake directory nor its parent exists, which happens only when miner.intake_dir names a custom path; doctor will not build a tree to test it. An OK speaks only for your terminal, not an agent's sandbox. With Codex, re-running jevlin agents install fixes a NO.

up to date UNKNOWN saying the last check ran days ago means no agent with the hooks has started a session since. Open one, or upgrade by hand. See Upgrading.

Your region is refused

The rewards service can refuse mining by the address you connect from. Search is never affected. status shows a region: line for the last refusal, and doctor's joined this epoch says which one kept you out:

code	meaning
REGION_RESTRICTED	The address is in a jurisdiction the rewards service cannot serve, or one it could not determine.
REGION_INELIGIBLE	Mining rewards are not available there.
REGION_UNVERIFIED	The address looks like a VPN, proxy or Tor exit, so its region cannot be told. This one is a hold, not a refusal: connect directly and the next attempt is decided afresh. Nothing is forfeited.

A flush asks again each time it talks to the rewards service, and jevlin join asks at once. Searches recorded meanwhile wait rather than being submitted. See Earning with mining.

jevlin join            # ask the rewards service again now

The claim link is lost, or the registration expired

For a registration that is still unclaimed, a foreground jevlin connect asks the platform for a fresh link and prints it. The old code is dead the moment a new one is minted. An unclaimed registration that expires is replaced by the next jevlin connect you run, changing only the platform agent and its key.

jevlin connect          # print the claim link, or mint a fresh one

If the platform no longer recognizes the key, connect stops. Only then:

jevlin connect -force   # replaces the credential; run it on purpose

status saying the registration on file could not be read means a damaged local record. jevlin connect rebuilds it from the platform. See Setup in detail.

The config names old hosts

The rewards service moved on 16 October 2026. An installation set up before then keeps the old address in its config, because Jevlin never rewrites your config: searches work, but nothing earns, and jevlin doctor says it cannot reach the authorization server, which is "off-origin". Change one line in the [mining] table:

[mining]
as_url = "https://rewards-testnet.jevlin.ai"

Then run jevlin flush and jevlin doctor. Your authorization, wallet and payout address carry over. If you use Codex, also run jevlin agents install -client codex and answer yes, so that Codex's sandbox lets the flush reach the new address.

An installation set up with v0.1.0 or earlier also names the old router and platform, whose key the current router does not accept. To earn again it registers afresh: keep the wallet's recovery phrase or move its funds out, remove the installation with jevlin uninstall -purge-state, and set the current release up. See the changelog.

A non-ASCII query is mangled on Windows

Windows PowerShell 5.1 turns every non-ASCII character into ? on the way to a program unless the output encoding is set. The skill's PowerShell form starts with the line that sets it:

$OutputEncoding = [System.Text.UTF8Encoding]::new($false)

Use the form that matches your terminal. In Cursor, the PowerShell form run from Git Bash loses that line; use Git Bash's form, or ASCII queries. See Cursor.

status says no release check has run for this copy

The daily release check's record, update_check.json beside credentials.json, is about one binary at one version: the one a check ran as, an upgrade installed or a rollback restored. A record left by another binary, or by this one at an earlier version, counts as none, so a copy that has just been installed by hand, or a second installation sharing the file, reports no check of its own until it has run one. Nothing is wrong: the next agent session starts that copy's check. To check now:

jevlin upgrade

See Upgrading.

Still stuck

jevlin doctor -json and jevlin status -json carry everything the text reports do, in one envelope each. Open an issue at github.com/jevlinai/jevlin-go with their output; neither contains your key, your wallet or your queries.