Troubleshooting¶

Find the problem you see, grouped by where it happens, with the message Tuneline Studio shows and how to fix it.

When a step fails, its message on the canvas and the run's error usually say what went wrong and what to do. Start there, then look up the symptom below. For the full picture, open the run's Logs tab (see Where to find logs).

Using the app¶

"A new version is ready"¶

Tuneline Studio was updated after you opened the tab, and the page you opened no longer exists in the old version. The app reloads itself once to fix this; when you see the message, press Reload page. If it keeps appearing, check your connection, then reload again.

"This page didn't load"¶

Something went wrong while showing the page. The message under the heading says what. Press Reload page, or open another page from the sidebar. If it keeps happening, note what you clicked and report it.

Signing in¶

There's no Create account or Email me a link¶

New accounts are created with Continue with GitHub or Continue with Google; the sign-in page no longer sends email. If neither button appears, the site isn't taking new accounts right now. Accounts that already have a password can still sign in with their email and password.

GitHub or Google sends you back to `localhost`¶

This is a setting of the Tuneline installation, not of your account. The person who operates it must set the Site URL and Redirect URLs in Supabase (Authentication → URL Configuration) to the app's address, for example https://tuneline-studio.vercel.app and https://tuneline-studio.vercel.app/**. See Self-hosting.

"To create an account, your GitHub or Google account's email must be a Gmail, Yahoo, Outlook or work (organization) address"¶

Accounts are open to Gmail, Yahoo and Ymail, Outlook (outlook.com, hotmail.com, live.com, msn.com) and work or school addresses. Other free email providers (for example iCloud, Proton, AOL or GMX) and throwaway inboxes can't create accounts. The address that counts is the one on your GitHub or Google account: on GitHub, your primary email (Settings → Emails). Make an accepted address your primary one, or use the other button. If your organization's domain is refused by mistake, ask the operator of the installation to allow it.

You chose Cancel on GitHub or Google, or refused access. Choose the button again and approve the sign-in.

Tuneline needs a verified email address from the account you sign in with. On GitHub, add and verify one under Settings → Emails, then try again.

The operator turned that sign-in off after the page loaded. Reload the page and use one of the buttons it shows, or your email and password.

"This account's email address was never confirmed"¶

The account was created with email and its address was never confirmed, so its password can't be used. Choose Continue with GitHub or Continue with Google with the same email address instead: that opens the account.

Starting a run¶

"This pipeline needs ... Add them in Settings"¶

The Run dialog lists keys the pipeline needs that you have not saved, and why, for example "This pipeline needs RunPod API key (deploy: Create the RunPod endpoint). Add it in Settings."

You can either:

add the key in Settings → API keys (see API keys and security); or
remove what needs it. The Sanctions alert triage template ends with a Deploy endpoint block that serves the model on RunPod Serverless by default, which is what asks for the RunPod key. If you don't want an endpoint yet, select that block and press Delete node, or change Where to serve to a provider whose key you have.

The same check runs on the server, which answers "Add these API keys in Settings → API keys before running: ..." when a key is missing.

The first estimate or page load is slow¶

After a quiet period, Tuneline's server starts up again on the first request, so the first estimate in the Run dialog or on the Hardware page can take a few seconds. Later requests are fast.

My computer runs¶

The run stays Queued: "Waiting for your computer"¶

A My computer run waits in Queued until one of your connected computers picks it up. The banner above the canvas and the Waiting for your computer box on the run page tell you which case you are in:

Message	What it means	Fix
""office-4090" is online and starts this run within 30 seconds."	All good.	Wait.
"Waiting for your computer: it isn't connected. Finish its one-time setup in Settings → Your computers." / "No computer is connected."	You have not connected a computer yet.	In Settings → Your computers, press Add a computer and run the setup (see Your own computer). The run starts as soon as the computer connects.
""office-4090" hasn't been set up yet."	You added the computer but never ran its setup file or command.	Run the setup. If you no longer have the setup file, remove the computer in Settings and add it again.
""office-4090" is offline."	The computer is off, asleep, or its worker stopped.	Turn it on and sign in (on Windows the worker starts by itself), or run the install command again.

A computer counts as online when its worker has checked in within the last 90 seconds. In Settings → Your computers it shows Online or Offline.

To run just this one run without setting up a worker, open Or start just this run from a terminal on the run page and run the command on any machine with Python 3.10 or newer.

A queued My computer run is failed after 14 days if nobody picks it up; press Run again when your computer is ready.

"The worker token was rejected"¶

The installer or the worker log says "The worker token was rejected. Add the computer again in Settings -> Your computers and use the new command."

The computer was removed in Settings, or the token was mistyped. Add the computer again in Settings → Your computers and use the new setup file or command. Each computer's token is shown only once.

The installer stops with an error¶

Message	Fix
"Python 3.10 to 3.13 is required."	Install Python from python.org (on Windows tick Add python.exe to PATH; on macOS `brew install python@3.12`; on Ubuntu `sudo apt install python3 python3-venv`), then run the command again.
"Installing PyTorch failed. Update your NVIDIA driver and try again."	Update the NVIDIA driver, then run the command again.
"Installing the runner failed. If bitsandbytes is the problem, use WSL2 (Ubuntu) and the Linux installer."	See QLoRA on Windows.
"This script does not know your Tuneline address."	Copy the full command from Settings → Your computers instead of downloading the script by hand.

"Lost contact with the worker"¶

The run failed with "Lost contact with the worker: no heartbeat for 20 minutes. Check that it is still running, then Retry." The computer went to sleep, lost its internet connection, or the worker was stopped during the run. Keep the computer awake and online, then press Run again.

Cloud providers¶

A run stays Launching¶

The job is starting at the provider. The first Modal launch builds the job image, which can take several minutes, and Kaggle can queue jobs for a while. Open the provider's console (Modal apps, RunPod pods, Kaggle notebooks, Hugging Face jobs) to see the job's own log.

Tuneline Studio checks active runs in the background. If the job never starts, the run fails with "The job did not start within 60 minutes. Try another GPU or provider." (180 minutes on Kaggle), or "The launch did not complete (no job id was recorded). Retry the run."

Hugging Face Jobs: 402 or "Jobs need a positive credit balance"¶

Hugging Face Jobs are billed to your Hugging Face account, which needs credit. Add credit at huggingface.co/settings/billing (PRO monthly credits count), then run again. Or pick another place to run.

Kaggle refuses to start¶

"GPUs and internet in notebooks need a phone-verified Kaggle account": verify your phone number at kaggle.com/settings.
"Your weekly GPU quota may be used up": Kaggle gives about 30 GPU hours a week. Wait for the weekly reset or run elsewhere.
"Kaggle rejected your credentials": create a new API token and save it again in Settings → API keys.

"The job ended without reporting a result"¶

The provider's job stopped before the runner could report (for example it was preempted or ran out of disk). Open the provider's logs for the cause, then press Run again. Finished steps are reused from the cache.

During training¶

Out of memory¶

The step fails with "The GPU ran out of memory." Try, roughly in this order:

QLoRA instead of LoRA or full fine-tuning (Method on the training block).
A shorter Max sequence length (tokens). Memory grows quickly with it.
A smaller Batch size per GPU with more Gradient accumulation, which keeps the effective batch the same.
Gradient checkpointing on (it is on by default).
A smaller model, or a GPU with more memory.

The Run dialog and the Hardware page estimate memory before you run; see Hardware and costs.

QLoRA on Windows¶

QLoRA needs the bitsandbytes package and an NVIDIA GPU. When it is not available, the log says "bitsandbytes is not available: training uses LoRA instead of QLoRA." (or, on a machine without an NVIDIA GPU, "QLoRA needs an NVIDIA GPU ...") and the run continues with LoRA, which uses more memory. QLoRA is most reliable on Windows under WSL2: install Ubuntu in WSL2 and connect it with the Linux command from Settings → Your computers. On macOS, QLoRA is not available.

Training on the CPU is very slow¶

Without a GPU, only the CPU smoke test and very small models are practical: the smoke test (a 135M-parameter model, 20 steps) takes a few minutes. For real models, use a GPU: Kaggle and Colab have free ones. See Running pipelines.

"A Python package is missing on this machine"¶

Run the install command from Settings → Your computers again: it reinstalls the runner with its training packages. When running by hand, install tuneline[train].

"The disk is full"¶

Free some space (downloaded models are large), or use a machine with a larger disk.

Models and Hugging Face¶

Gated model: access refused, 401 or 403¶

The step fails with "...: the repository is gated. Accept its terms on huggingface.co with the account that owns your Hugging Face token, then run again." or "Access to ... was refused."

Open the model's page on Hugging Face (Llama, Gemma and some Mistral models are gated), sign in with the account that created your token, and accept the license. Access is sometimes granted after a review. Then run again.

"Your token may be missing, read-only or expired"¶

Pushing to Hugging Face failed. Your token probably has the Read role. Create a token with the Write role, replace it in Settings → API keys and press Test.

"... ships custom code. Turn on 'Trust remote code'"¶

Some models need their own Python code. Turn on Trust remote code in the Base model block's advanced settings, but only for repositories you trust.

Evaluation and quality gate¶

"Quality gate failed"¶

The run failed with a message such as "Quality gate failed: label_recall_escalate = 0.95 (needs >= 0.98)", and later steps were skipped. The model did what the message says: it scored below your threshold.

Look at the Evaluation tab: the failing rule, the measured value, and the sample outputs the model got wrong.
Improve the model (more or better training data, more epochs, a larger base model), or, if the threshold is stricter than your test set can measure, adjust it. See Choosing thresholds.
If a failing gate should not count as an error, set When a rule fails to Skip later steps, keep the run successful.

"... is missing" or "not in this report"¶

A gate rule names a metric the report doesn't have. The gate's error lists the available metrics; compare the spelling. Label metrics use lowercase labels (label_recall_escalate, not label_recall_ESCALATE), and base. and delta. metrics exist only when Also score the base model is on.

"The label regex matched none of the expected answers"¶

The Label regex of Evaluate on test set does not find a label in your expected answers, so there are no label metrics. Change it to match your answer format; its first group must capture the label.

Deployments and playground¶

An endpoint takes minutes to answer¶

A scale-to-zero endpoint starts a GPU and downloads your model on the first request after a quiet period. This can take a minute or more, and several minutes the first time. Set Always-on workers to 1 to avoid it (you then pay for the GPU all the time). See Deployments.

"This endpoint is stopped. Resume it (or create a new one) first."¶

Press Resume on the Deployments page. Modal endpoints stop after their time limit; resuming starts a new one with a new URL and key.

"Add your Hugging Face token in Settings → API keys to chat with Hub models"¶

Chatting with a Hub model in the Playground uses Hugging Face Inference Providers with your Hugging Face token. Add it in Settings.

"Hugging Face didn't accept your token for Inference Providers"¶

Your token can't call Inference Providers. Fine-grained tokens need the Make calls to Inference Providers permission: create a token with it at huggingface.co/settings/tokens (a token with write access also works) and save it in Settings → API keys.

"No Inference Provider serves … for chat right now"¶

Pick a model from the Model list: it holds the models Inference Providers serve right now. Your own fine-tuned models are private, so no provider serves them: deploy one on the Deployments page and chat with the endpoint instead.

"… is a gated model"¶

Open the model's page on Hugging Face with the account that owns your token and accept its license, then try again, or pick another model.

"Your Hugging Face account has no Inference Providers credit left"¶

Hugging Face bills Inference Providers to your account. Add credit or a payment method at huggingface.co/settings/billing, or chat with one of your own endpoints.

Where to find logs¶

Run log: on the run page, Logs tab. Filter by step and level, and press Download to save the full log as a text file.
Worker log on Windows: %USERPROFILE%\.tuneline\worker.log. The worker runs hidden in the background; stop it with %USERPROFILE%\.tuneline\stop-worker.ps1.
Worker on Linux and macOS: the worker prints to the terminal where you started it.
Provider logs: the provider's console (Modal, RunPod, Kaggle, Hugging Face). The run page shows the provider's Job id to find it.
Checking your computer: run tuneline doctor (from ~/.tuneline/venv) for a report on Python, PyTorch, CUDA, GPUs, packages and connectivity. See the runner CLI reference.

Still stuck? See Ask a question.