Skip to content

Troubleshooting

In short

  • Find what you see below, in bold: the message, or what is wrong. Each entry says why it happens and what to do.
  • The container's own log tells you most of what the app can't: docker logs parleml.
  • A failed job keeps its log. Open the experiment's Run & artifacts → Console tab.
  • Settings → Agents and Settings → Diagnostics show what this server can do right now.

Starting ParleML

The page at http://localhost:8000 does not load. The server takes about a minute to start. Run docker logs parleml: it is ready at the line Application startup complete. Then refresh the page.

Docker says port 8000 is already in use. Another program has the port. Publish ParleML on another one, such as -p 8080:8000, and open http://localhost:8080.

The container stops at once, and its log says "PARLEML_CORS_ORIGINS cannot contain '*'". A wildcard would let every website use a signed-in person's session. List the exact origins instead, or leave the variable unset.

The log says "PARLEML_PUBLIC_URL must be an absolute http(s) URL…" or "PARLEML_OAUTH_ISSUER must be an http(s) origin…". Give a full address with its scheme, such as https://parleml.example.com. The OAuth issuer takes no path.

Agents and sessions

Settings → Agents shows the agent as Not signed in. The agent CLI in the container has no account. Sign it in, or pass its API key, as in Run ParleML. Not installed means the CLI is not in this image: Claude Code and Cursor come with the extended image.

A session shows "Paused · sign-in needed". The agent's sign-in ran out or was never made. The banner says how to fix it for that agent, for example codex login or setting OPENAI_API_KEY. Then choose Resume after signing in.

A session shows "Paused · provider limit". The account the agent signs in with reached its usage limit. This is not a ParleML failure, and nothing is lost. Tick Resume automatically when the limit resets, or Resume now once you have more quota. Starting new sessions does not help: they use the same account.

A session shows "Attempt limit reached". The attempt used its turn or time budget. Resume starts another attempt with a fresh budget and keeps what was done. To raise the budget, change the profile's limits.

A session shows "Process lost" or "This session needs recovery". The agent process stopped, for example because the container restarted. Resume continues from the work already saved.

The agent never uses a skill you added. Agents match a request against the skill's description. Make it say when the skill applies. See Add your own skill pack.

More: credentials and preflight, session recovery and agent troubleshooting.

Datasets

"No EDA cached for this dataset yet." Profiling does not run on its own unless an administrator turns on Run EDA automatically after a dataset is added (Settings → Workspaces & data). Choose Run EDA at the top of the dataset page.

"Upload exceeds the maximum size of 512 MiB." The file is larger than the server allows. Raise PARLEML_MAX_UPLOAD_MB and restart, or connect the database the data comes from instead.

"Workspace '…' is archived, so it is read-only." Someone archived the workspace. A person can restore it under Workspaces → Archived.

Experiments and jobs

An experiment says "Queued behind N other job(s)". The server runs only so many heavy jobs at once, and the rest wait their turn. The message says how many are running. To run more at once, raise PARLEML_JOBS_HEAVY_CONCURRENCY, but each fit then gets fewer cores. See Configuration.

A job fails with "The worker ran out of memory…" or "The worker was killed (SIGKILL, exit 137)…". The server had too little memory for the job. Nothing is wrong with the model or the data. Give Docker more memory (Docker Desktop → Settings → Resources), run fewer jobs at once, or choose a lighter template such as Quick Explore.

A job fails with "The worker made no progress since…". It used no CPU for longer than the stall limit (15 minutes by default), so the server stopped it. Run it again. If it stalls again, its log holds the stack of every thread, which shows where it waits.

The Explain view says "Explanations appear once the run has finished fitting." The experiment is still training, or it failed. Wait for it to finish. Then choose Compute explanations in the experiment's header: explanations are a separate job.

A view answers "Explanations have not been computed for this experiment yet". Predictions do not need the explanations, but the reasons behind them do: drivers, rules, archetypes, local analysis and reason codes. Choose Compute explanations in the experiment's header, wait for it to finish, then open the view again.

Scoring answers "This experiment has no fitted model on disk to score with". The trained model is missing from the experiment's folder. Train the experiment again. A bring-your-own model scores through its explanations, so compute them first.

A scoring job fails with "Source dataset is missing model features: …". A column the model was trained on is not in the new file. The message lists them. See Score a new file.

The run's events show "This run was not tracked in MLflow". MLflow logging failed, but the run itself finished and its results are complete. The event gives the reason, such as an unreachable tracking server. See Track a run in MLflow.

Settings → Diagnostics lists a model as "Not cached; downloads are off". The server is set to work offline (HF_HUB_OFFLINE) and the model's weights are not in its cache. Allow downloads, or put the weights in the cache (HF_HOME).

Model downloads fail with CERTIFICATE_VERIFY_FAILED. A corporate proxy re-signs HTTPS traffic with its own certificate. ParleML trusts the operating system's certificates by default; add the proxy's root certificate there. Don't set PARLEML_DISABLE_TRUSTSTORE.

Sign-in and tokens

"Login session expired — please try again." The sign-in took too long or started in another tab. Start again from ParleML. More fixes are in Set up single sign-on.

"This action requires an administrator role." Your email is not in PARLEML_ADMIN_EMAILS. Ask whoever runs the server to add it, then sign in again.

A token is refused with "This token was minted with the retired scope…" or "This builder token was minted before builder tokens expired…". The token comes from an older release. Mint a new one under Settings → Access → API tokens, and put it in the agent's configuration.

A builder call fails with "Builder requests need an Idempotency-Key header…". Every builder request that changes something must send an Idempotency-Key header. See the API reference.

Results

My numbers differ from a tutorial or a screenshot. The samples are synthetic, and results depend on the template, the agent's choices, library versions and the machine. A screenshot is an example, not a promised score. Compare your own experiment's evidence instead.

Still stuck

Read ML4 troubleshooting for training errors. To report a problem, include the failing step, the message, and docker logs parleml output, with credentials and sensitive data removed.

Next