Troubleshooting

Work from the bottom up: is the Runtime running, is the key right, does the provider or runtime work, is the model there, and only then the app.

When you ask for help, include the request ID from the error or the response headers. Never paste keys, prompts or replies into a support request.

Nexus is offline

The Console says Msty Nexus Runtime is unavailable, or the menu bar says Offline.

1. In the menu bar panel, click Reconnect. It refreshes the app’s private connection to the Runtime.
2. Still offline? Click Restart Runtime.
3. Check that nothing else uses the port: 3939, or 3949 for Business.

If you’re managing another machine, check that it’s on and connected. The machine switcher shows which machine you picked.

Business or headless machines: a machine removed from Fleet, or whose license has ended, returns MACHINE_LICENSE_REQUIRED. Ask an admin to add it again with a new setup command.

The app’s key is rejected

The app gets UNAUTHORIZED.

1. Open Connections and make a new key with Create API key.
2. Put it in the app as its API key.
3. Check the app sends it in one header: Authorization: Bearer, X-Msty-Nexus-Token or x-api-key.
4. Revoke the old key once the app works.

A provider’s key, such as an OpenAI key, never works with Nexus. Apps need a Nexus key.

A provider won’t connect

Check connection fails on the provider.

• Is the provider turned on, with its key set?
• Is the address right? (For compatible APIs.)
• Can the account list models? Some keys are limited.
• Does the provider support what you’re asking, such as embeddings?

The check says why: a missing key, wrong settings, rejected, unreachable, or an answer Nexus couldn’t read.

No models show up

• Online provider: wait for its models to load, or check Models shared with apps in the provider’s settings.
• Local runtime: make sure it’s running in Providers → Local runtimes.
• A model server you run yourself: open Providers → Discovery and click Scan this machine.
• Hidden models: change the filter in Models.
• Mixed-up model files: open Models → Library health and click Run suggested repair.

A request fails

Look at error.code in the reply:

Code	Fix
MODEL_NOT_FOUND	Check the name. Copy it with Copy model id in Models.
MODEL_ENDPOINT_NOT_SUPPORTED	The model can’t do this kind of request. Use a model that can, such as an embedding model for embeddings.
PROVIDER_NOT_CONFIGURED	The provider is missing its key.
INFERENCE_BUSY	Every local slot is busy. Retry, or see Settings for how many requests a runtime takes at once.
DATA_PROTECTION_BLOCKED	Data Protection stopped it on purpose.
FEATURE_NOT_ENTITLED	Your plan or this machine doesn’t include the feature. See Plans.

Also check:

• The local runtime behind the model is running.
• A Smart Route’s fallback works.
• Image edits and transcriptions use a model ID or alias, not a preset or route.

Search for the request ID in Activity to see what happened.

A web page can’t reach Nexus

Tell the two problems apart:

• The browser blocks it before it reaches Nexus: add the page’s origin to Allowed browser origins in Settings.
• Nexus answers UNAUTHORIZED: the key is wrong.
• Another device can’t connect at all: turn on Private network access in Connections → Gateway access, and restart the Runtime.

Allowing an origin doesn’t open Nexus to your network. Those are separate switches.

A runtime won’t start or update

• Is it turned on, and supported on this system? MLX needs an Apple Silicon Mac.
• Is another task already working on it? See Activity.
• Is its port free?
• Stop it before you update it, if Nexus asks.

Nexus only controls runtimes it started. If you started one yourself, stop it yourself first.

A model won’t download, load or delete

• A download may be waiting behind another download or a runtime setup. See Activity. Waiting downloads pick up again after a restart. Keep the machine on until the download is checked.
• A model that doesn’t fit in memory won’t load. Unload others, or pick a smaller one.
• A model used by a preset or Smart Route can’t be deleted until you change them.
• Nexus only deletes files it manages. It won’t delete a model file elsewhere on your disk.

GPU placement warnings

Warning	Means
GPU_FALLBACK_TO_CPU	The model ran in system memory, not on the GPU as planned
GPU_PLACEMENT_VERIFICATION_LIMITED	The model loaded, but Nexus couldn’t fully confirm it’s on the GPU

In the model’s details, under Placement: click Plan placement, review the plan, then Apply plan. If it’s worse, click Roll back.

The Cluster is degraded

1. Open Cluster and click Check cluster.
2. Look at each Mac: reachable, Local Network permission, Nexus version, Thunderbolt cables and RDMA, and memory a stuck worker didn’t free.
3. If a Mac changed address, use the reconnect action it offers.
4. If a worker didn’t free GPU memory, stop traffic and restart that Mac.
5. After changing any cable or port, check the cluster again and reload the model.

Don’t keep retrying a model split across Macs after one Mac is lost. It stops on purpose, because it can’t serve safely with a piece missing. See Cluster.

Subscription models disappear

Open Providers → Subscriptions. Start the subscription runtime if asked, turn the account on, or click Re-authenticate if the sign-in expired. Wait for the models to load before you try Chat Lab again.

Subscription models and Gauge readings refresh separately, so a model can come back before its newest reading.

A preset shows warnings

The preset has a setting its model may not support.

Warning	Means
unsupported_param	The provider doesn’t list this setting
unsupported_thinking	The model can’t use thinking settings
unsupported_thinking_display	The provider can’t show reasoning the way you asked
unsupported_prompt_cache	Prompt caching doesn’t work with this model
unknown_provider_bucket	Provider options for a provider type Nexus doesn’t know

Change the model, remove the setting, or keep it if you plan to switch models later. See Presets.

Gauge shows nothing

• Is Gauge on? On the Gauge page, click Turn on Gauge.
• Is the account connected and turned on, with a valid sign-in or key?
• Has a refresh finished?
• Does the date range have data?
• Does the provider report this number at all?

See Gauge.

Look at the logs

• Activity → Diagnostic logs shows Runtime and cluster-worker logs, searchable by request ID.
• The menu bar panel’s Show logs opens the app’s logs.
• From a terminal: msty-nexusctl doctor, or msty-nexusctl logs read --request-id <id>. See Command line.
• For Smart Route problems, Export for support on the route (or msty-nexusctl routes export) saves a file without any message text or keys.

Reset a Mac installation

Use this only when Reconnect, signing out, and reinstalling haven’t helped. Run it as your normal user, without sudo:

curl -fsSL https://nexus-assets.msty.ai/app/reset.sh | bash

It finds Msty Nexus or Msty Nexus Business and offers:

• Fresh start: clears sign-ins and settings. Keeps the app and downloaded models.
• Uninstall: removes the app and its data. Keeps downloaded models.
• Uninstall and delete models: removes the app, its data and downloaded models.

You type RESET to confirm. Files go to a dated folder in the Trash where possible. Deleted Keychain sign-ins can’t be recovered. Development builds and headless fleet Runtimes aren’t touched.

To see what it would do first, without changing anything:

curl -fsSL https://nexus-assets.msty.ai/app/reset.sh | bash -s -- --personal --fresh-start --dry-run --details

Use --business instead of --personal for Msty Nexus Business. Save anything you need before you run it for real.