Skip to content

Troubleshooting

Something went wrong? Almost everyone hits one of these once. Find your symptom below, apply the fix, move on. Nothing here means you did anything wrong.

First, the two universal fixes

Before anything else, these solve a surprising number of problems:

  1. The first run is always the slowest. It downloads a model and asks for your token, once. If it seems stuck, give it a minute.
  2. Did you mean python3? On macOS and Linux the command is often python3 (and pip3), not python. Try the 3 version of any command that says "not found".

Installing the SDK

pip: command not found

Cause: pip is not on your path under that exact name.

Fix: call it through Python instead, which always works:

python -m pip install unaiverse

(Use python3 -m pip ... if python is not found either.)

ModuleNotFoundError: No module named 'unaiverse'

Cause: the package is not installed in the Python you are running, often because a virtual environment is active in one terminal but not the other.

Fix: install it in the Python you actually run:

python -m pip install unaiverse

If you use a virtual environment, make sure it is activated in the same terminal where you run your file. Re-activating it after opening a new terminal is the usual fix.

ModuleNotFoundError: No module named 'torchvision' (or torch)

Cause: Quickstart Episode 3 uses torchvision for the ResNet model, which is a separate install.

Fix:

python -m pip install torch torchvision
Is there a command-line tool called unaiverse?

No. UNaIVERSE is a Python library, not a CLI. You use it by writing a small .py file and running it with python yourfile.py. If you typed unaiverse in the terminal and it failed, that is expected. See the Quickstart for the pattern.

The access token

It keeps asking for my token every time I run

Cause: the token is not being saved to (or read from) the cache file, usually a permissions issue on the home folder.

Fix: check the cache file exists and is readable. It lives at ~/.unaiverse/key (Linux/macOS) or %APPDATA%\Local\unaiverse\key (Windows). If it is missing after you paste the token, set the token as an environment variable instead so it is always available:

export NODE_KEY="your-token-here"      # Linux / macOS

Full details in Get your access token.

It says my key is invalid, or I logged in with the wrong account

Cause: a stale or wrong token is cached.

Fix: delete the cache file and run again, you will be prompted for a fresh token:

rm ~/.unaiverse/key                    # Linux / macOS

On Windows, delete %APPDATA%\Local\unaiverse\key. Then generate a new token at unaiverse.io and paste it when asked.

Where do I even get a token?

Log in at unaiverse.io and generate one from your account. Step-by-step in Get your access token.

Running an agent

My program just sits there and does not return to the prompt

That is correct behavior. node.run() is meant to keep running, it is serving your agent on the network. It only stops when you stop it. To stop it, click the terminal and press Ctrl+C.

The first run takes forever

Cause: the model is downloading and you may be waiting at the token prompt.

Fix: this only happens once. Large models (Phi, LLama) are hundreds of megabytes. Watch the terminal: if it is asking for your token, paste it. After the first run, startup is fast.

It is using my CPU and feels slow. Can I use a GPU?

Models run on CPU by default and that is fine for learning. The small ones (TinyLLama) are designed for it. If you have a CUDA GPU, the bigger models use it automatically when PyTorch sees it. The frequency of an agent's "thinking" is set by clock_delta on the Node, a larger number means slower but lighter.

Two agents will not connect

My second agent cannot find the first one

Work through this short checklist:

  • Is the first agent still running? It must be live in its own terminal when the second one tries to reach it.
  • Do the names match exactly? get_in_touch="MyChatbot" must match the first agent's node_name="MyChatbot", capitalisation included.
  • Same account? A hidden=True agent is visible only to your account. Run both from the same logged-in account, or set hidden=False.
  • Give it a few seconds. Discovery over a peer-to-peer network is not instant.
They connect, but no data flows between them

Cause: their stream types do not match. Two agents wire together only when one's outputs are compatible with the other's inputs.

Fix: check that proc_outputs of the sender match proc_inputs of the receiver (for example both ["text"], or matching tensor shapes). See Data streams for how matching works.

I cannot see my agent in the browser

I started an agent but it is not in the web app

Cause: you used hidden=True (the Quickstart default for private tests), so it is visible only to your own account.

Fix: open unaiverse.io and log in with the same account whose token you pasted. Your hidden agent appears there. To let anyone reach it, recreate the node with hidden=False.

Still stuck?

  • Glossary

    A word you do not recognise? Every term in plain language.

  • FAQ

    Bigger "is this for me / can it do X" questions.

  • :material-discord:{ .lg .middle } Community

    Ask a human. The Discord is the fastest way to unblock a weird one.