Troubleshooting

Start with neuraframe doctor: it runs the preflight and summarizes service and license state, which points at most issues quickly.

Install failed

The installer stops on a clear reason if the preflight does not pass. Re-run with detail to see what failed:

sudo bash install.sh --verbose

Common causes: not run as root, missing systemd, or a system below the supported OS, kernel, or driver floor. Fix the reported item and re-run.

License not activating

Confirm the device can reach the internet and that you are using the email tied to your subscription. Check the fingerprint and current state:

neuraframe license

If the device is offline, use offline activation: send the fingerprint and receive a signed license file to install. See Licensing & trial.

Trial expired

When the trial ends, NeuraFrame™ enters pass-through mode. Your model still answers; reuse is off. Subscribe and activate to restore features:

sudo neuraframe activate     # needs sudo: writes a license file
neuraframe status

Answers look like pass-through

If status shows pass-through and sources read model_passthrough, the license is expired or missing. Refresh or activate:

neuraframe license refresh
sudo neuraframe activate     # needs sudo: writes a license file

Model not reachable

If requests fail or always hit the model, check the configured endpoints and that your model is running:

neuraframe config get
neuraframe logs

Set the correct completion and embedding URLs and restart the service (see Using NeuraFrame™).

Billing issue

Manage payment methods, invoices, and cancellation from the portal:

neuraframe billing

A failed payment does not immediately disable anything; if it stays unresolved past the paid period, the device moves to pass-through until renewed.

Update cannot reach the update service, or reports a wrong installed version

neuraframe update checks a signed release manifest hosted on our CDN and prints the exact URL it tried when it cannot connect; if your network uses a proxy or firewall, allow-list that URL. Builds before 0.5.2 could also report installed: 0.0.0 when the command was run through its /usr/local/bin link; upgrading fixes it. Either way, the manual path always works: download the current package from the download page and run the installer over the top. Your license, configuration, and reuse memory are preserved automatically, and the memory store migrates itself.

status says not licensed, but doctor says the license is valid

Fixed in 0.5.2: status now re-checks the license on every call, so it agrees with doctor immediately after a trial or activation. On an older build, restarting the service (sudo systemctl restart neuraframe-studio) brings status back in line, or upgrade.

Still stuck?

Gather a quick diagnostic and contact us:

neuraframe doctor