Troubleshooting

Use this page to map common CLI messages to fixes.

Configuration Errors

Message	Cause	Fix
`Path is required.`	The command did not receive a file or folder path.	Pass `optimus check <path>`.
`Path not found: ...`	The path does not exist.	Check the path and working directory.
`--env must be 'test' or 'prod'.`	The environment value is invalid.	Use `--env test` or `--env prod`.
`--verbose and --quiet cannot be used together.`	Conflicting console output options.	Pick one option.
`Check type is required...`	No check type was resolved.	Use `--standard`, `--qualified`, or `defaults.checkType`.
`Column 'vatId' must be mapped...`	No VAT ID column was mapped.	Add `--col-vat-id` or `columns.vatId`.
`--base-url must be an absolute URL.`	The URL is not absolute.	Use a full URL such as `https://example.test/`.

Message	Cause	Fix
`Could not load YAML file...`	YAML is missing, unreadable, or invalid.	Check file path and YAML syntax.
`Mapped column '...' was not found in the CSV header.`	Mapping references a header that does not exist.	Fix the header name or mapping file.
`must be a 1-based column index when --no-header is used.`	No-header mode is using a name or invalid index.	Use `1`, `2`, `3`, and so on.
`Unknown input encoding...`	Unsupported encoding.	Use `utf-8`, `windows-1252`, or `iso-8859-1`.
`Unknown output encoding...`	Unsupported output encoding.	Use `utf-8`, `windows-1252`, or `iso-8859-1`.
`Unknown output column...`	`output.columns` or `--out-columns` contains an unknown name.	Use a reserved output column, shortcut, or configured custom column.
`Invalid regex in skipPattern...`	The filter regex is invalid.	Fix `filter.skipPattern`.

Message	Cause	Fix
`No token configured...`	API run without a token.	Set `OPTIMUS_TOKEN` or use `--token`.
`Token is invalid or expired.`	API rejected the token.	Create or request a new token.
`Quota exhausted. Please check your license.`	API returned HTTP 402.	Check license or quota.
`Rate limit reached. Please wait and try again.`	API returned HTTP 429.	Retry later.
`Connection timeout...`	API did not respond in time.	Retry later or check network connectivity.
`Server error (...)`	API returned HTTP 500 or higher.	Retry later. If it persists, contact support.

Message	Cause	Fix
`Saved validation state does not match...`	The file, options, request hash, or API target changed.	Use `--force-new` if you want a new operation.
`Saved validation state is unreadable...`	The state file is corrupt.	Use `--force-new` in an interactive run or remove the state file if appropriate.
`Saved validation operation is no longer available...`	The API returned 404 for saved operation lookup.	The CLI starts a new operation automatically.

Symptom	Cause	Fix
No files are processed.	No files match `pattern`, files are in subfolders, files end with `_result`, or files are younger than `minAge`.	Check folder root, file names, `pattern`, and `minAge`.
File moved to `error`.	The file hit a CLI, mapping, authentication, IO, temporary, or quota error.	Open the `.err` file and support log, fix the cause, then run folder mode with `--retry`.
File stays in `processing` with a duplicate destination message.	`onDuplicate` is `skip` and a file with the same name already exists in `done` or `error`.	Review the existing destination file. Then move/delete the processing file manually, or rerun with `--on-duplicate overwrite` or `--on-duplicate rename`.
File stays in `processing`.	The run was interrupted while the file was being processed.	Make sure no CLI process is still running, then move the CSV and its `.optimus-state.json` sidecar back to the folder root before running folder mode again.

When troubleshooting, run with verbose output and keep the support log:

optimus check customers.csv --map mapping.yml --standard --verbose --log-dir ./logs

Support logs are designed not to contain tokens, CSV row values, VAT IDs, company names, addresses, or custom column values.