Troubleshooting Guide
Common issues when running Ciaren. For broader questions, see the FAQ.
TIP
Run ciaren check to validate your environment in one shot — it reports a
non-writable data dir, a non-async database URL, an unreachable database, and the
available engines.
Database connection fails
Ciaren uses async SQLAlchemy. A plain sqlite://, postgresql://, or
mysql:// URL will not connect. Use the async variant in
CIAREN_DATABASE_URL:
sqlite+aiosqlite:///./ciaren.db(default)postgresql+asyncpg://user:pass@host/dbmysql+aiomysql://user:pass@host/db
Install the matching driver (asyncpg, aiomysql) for non-SQLite databases.
The schema is created automatically on startup, so there is no migration step.
"Port 8055 already in use"
Start the server on another port:
ciaren serve --port 8001Frontend can't reach the backend
The dev server proxies /api to http://localhost:8055 by default. If your
backend runs elsewhere, point the proxy at it:
VITE_API_TARGET=http://localhost:8001 npm run devIf the frontend port 5173 is taken, change it with VITE_PORT=3000 npm run dev
— and remember to add the new origin to CIAREN_CORS_ORIGINS.
A scheduled flow stopped running
A schedule is auto-disabled after several consecutive failed runs (default 5),
with a disabled_reason. Re-enable it to clear the streak. Manual run-now stays
out of the retry/auto-disable machinery. See Scheduling.
CORS errors
Add the calling origin to CIAREN_CORS_ORIGINS (a JSON list) in
backend/.env:
CIAREN_CORS_ORIGINS=["http://localhost:5173"]If API auth is enabled, browser clients can send either
Authorization: Bearer <token> or X-Ciaren-Token: <token>; both are allowed by
the API's CORS preflight handling.
Upload rejected as too large
The default upload limit is 100 MB. Raise it with
CIAREN_MAX_UPLOAD_SIZE_MB in backend/.env.
Module not found errors
Activate the environment you use to run Ciaren, then check whether the package is installed in that interpreter:
python -m pip show ciarenFor a PyPI installation, run python -m pip install ciaren in that environment.
For a source checkout, run python -m pip install -e . from the backend/
directory instead. Using python -m pip keeps installation tied to the selected
interpreter; a bare pip command can belong to a different environment.
For optional connector drivers, check the extras listed in
Installation and
Connections. For an async database driver such as aiomysql,
follow Database connection fails above instead;
the mysql connector extra installs pymysql, not aiomysql. Reinstalling the
base package does not add every optional driver. You do not need to delete your
existing virtual environment.
Exported pandas code fails after Split column
Symptom: the flow runs in Ciaren, but an older exported pandas script fails
with KeyError: 1 at _parts[1]. For example, splitting ['EU', None] on |
into region and city produces no second field in any row.
Cause: pandas only creates split columns that exist in the data. An older export can index a column that was never created, while Ciaren's runtime leaves missing fields null.
Workaround: check each split column before assigning it and use pd.NA for
a missing output. For the example above:
import pandas as pd
df_1 = pd.DataFrame({"location": ["EU", None]})
_parts = df_1['location'].astype('string').str.split('|', expand=True)
df_2 = df_1.assign(
region=(_parts[0] if 0 in _parts.columns else pd.NA),
city=(_parts[1] if 1 in _parts.columns else pd.NA),
)The result keeps region as ['EU', null] and city as [null, null]. Apply
the same check to each additional output; do not drop rows to avoid the error.
If your export already includes these checks, missing trailing fields are
expected nulls rather than an error. See the
Split column reference and the
split-column recipe for configuration and examples.
Install fails on Windows with a long-path error
A pip install can fail on Windows with an error like
OSError: [Errno 2] No such file or directory: '...\mlflow\store\db_migrations\versions\...'
and a hint about enabling long-path support. Ciaren bundles MLflow, whose
internal file paths are long, so installing into a deeply nested folder can push
the full path past Windows' legacy 260-character limit.
Fix it either way:
-
Enable long paths (recommended, one-time). In an Administrator PowerShell:
powershellSet-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' LongPathsEnabled 1Reopen your terminal, then reinstall. See the pip long-paths note.
-
Or install into a shorter path — create the virtual environment close to the drive root (for example
C:\ciaren\.venv) instead of a deeply nested directory.
ML training succeeds but the model isn't tracked (Windows)
A training run finishes green, its metrics show up, but the node's model URI and MLflow run id are blank — and a downstream Predict or Feature Importance node then fails because there's no model to load. The server log shows a warning like:
mlTrainClassifier: MLflow logging failed ([WinError 206] The filename or extension
is too long: '...\mlruns\...\models\...') — model trained but not tracked.This is the same Windows 260-character path limit as the install error above, but
at run time: MLflow writes artifacts under your tracking directory
(CIAREN_MLFLOW_TRACKING_URI, default ./mlruns inside the working directory),
and its nested mlruns/<exp>/<run>/models/... layout can push the full path over
the limit when Ciaren runs from a deeply nested folder. Training itself is
in-memory, so it still succeeds — only the logging step fails, which is why the
run is green but untracked.
ciaren check catches this ahead of time: when the tracking store is a local
folder and long paths are off, it prints an ml_path line — [warn] (with the
fix) if the path is long enough to be at risk, [ok] otherwise.
Fix it either way:
- Enable long paths (recommended, one-time) — the same
LongPathsEnabledregistry setting shown in the install section above. - Point the tracking store somewhere short — set an absolute, shallow
CIAREN_MLFLOW_TRACKING_URI(for exampleCIAREN_MLFLOW_TRACKING_URI=C:\mlruns), or run Ciaren from a directory close to the drive root. You can also edit the Local MLflow connection's Tracking URI in the Connections page.