Common Errors¶

Fast diagnosis for common runtime-integrator and plugin-author failures.

Config Validation Fails¶

Symptom:

ConfigValidationError

Typical causes:

Missing config file path
Unknown keys in strict model
Invalid values (for example top_k = 0)

Fix:

$ honestroles config validate --pipeline pipeline.toml

`doctor` Reports `fail`¶

Symptom:

honestroles doctor exits with code 1.

Cause:

One or more readiness checks failed (environment, config, input/schema, or output path checks).

Fix:

Run in table mode and apply the suggested fix values per check:

$ honestroles doctor --pipeline-config pipeline.toml --plugins plugins.toml --format table

Use a custom reliability policy file:

$ honestroles doctor --pipeline-config pipeline.toml --policy reliability.toml --format table

Use strict mode for CI:

$ honestroles doctor --pipeline-config pipeline.toml --strict --format table

In strict mode, aggregate warn becomes exit code 1.

`ingest sync` Fails with Invalid `source-ref`¶

Symptom:

source-ref may only contain letters, numbers, '.', '_' and '-'

Cause:

--source-ref contains unsupported characters (for example / or spaces).

Fix:

Use a valid connector identifier from the source glossary:

$ honestroles ingest sync --source greenhouse --source-ref stripe

See Ingest Source-Ref Glossary.

`ingest sync` Fails for Workable with HTTP 404¶

Symptom:

workable source-ref is invalid or not publicly exposed: '<ref>'

Cause:

The subdomain is incorrect.
The Workable account exists but does not expose public careers API endpoints.

Fix:

Confirm the company uses public Workable careers pages.
Use the Workable subdomain only:

$ honestroles ingest sync --source workable --source-ref your-company --format table

If the account is private, skip Workable ingestion for that source.

`ingest sync` Hits HTTP 429 / Backoff¶

Symptom:

Sync runs slowly and eventually fails with HTTP 429 or transient HTTP errors.

Cause:

Public endpoint rate limiting or temporary server issues.

Fix:

Reduce scope with --max-pages and/or --max-jobs.
Tune retry controls for your environment:
--timeout-seconds
--max-retries
--base-backoff-seconds
--user-agent
Re-run after cooldown; retries/backoff are built in for transient failures.
Split large sources into separate scheduled runs.

`ingest sync` / `ingest validate` Fails in Strict Quality Mode¶

Symptom:

Command exits with code 1 and quality check codes are present.

Cause:

--strict-quality escalates any non-pass quality result.

Fix:

Run validation first to inspect checks without latest overwrite:

$ honestroles ingest validate --source greenhouse --source-ref stripe --quality-policy ingest_quality.toml --format table

Tune thresholds in ingest_quality.toml only when justified. See Ingest Quality Policy Schema.
Re-run strict mode for CI gating:

$ honestroles ingest sync --source greenhouse --source-ref stripe --quality-policy ingest_quality.toml --strict-quality --format table

Common ingestion quality codes and fixes:

INGEST_QUALITY_NULL_RATE_COMPANY: map company fields (for example company_name) or use source fallback.
INGEST_QUALITY_NULL_RATE_POSTED_AT: map publishedAt|first_published|published_on|created_at.
INGEST_QUALITY_NULL_RATE_DESCRIPTION_TEXT: map plain-text description field or rely on HTML fallback.
INGEST_QUALITY_LOCATION_OR_REMOTE_SIGNAL: map at least one of location, remote, or work_mode.

`ingest sync` Returns Empty Result Set¶

Symptom:

rows_written = 0 with successful status.

Cause:

No public postings currently available.
Incremental state dropped already-seen postings.

Fix:

Run a full refresh to bypass state filtering:

$ honestroles ingest sync --source lever --source-ref netflix --full-refresh --format table

If you expected tombstones (inactive records) to be applied, confirm the run was coverage-complete. Truncated runs (hitting max-pages or max-jobs) do not apply tombstones.

If records look stale across runs, verify deterministic merge/retention controls:

--merge-policy updated_hash|first_seen|last_seen
--retain-snapshots
--prune-inactive-days

If warnings include INGEST_PAGE_REPEAT_DETECTED, the source repeated page payloads. Treat the run as coverage-incomplete and rerun later or with adjusted limits.

`ingest sync-all` Manifest Validation Fails¶

Symptom:

invalid ingest manifest ...

Cause:

Missing required [[sources]] entries.
Invalid key types in [defaults] or [[sources]].
Unsupported source values.

Fix:

Validate fields against Ingest Manifest Schema.
Use only supported sources: greenhouse|lever|ashby|workable.
Re-run:

$ honestroles ingest sync-all --manifest ingest.toml --format table

Reset Ingestion State¶

Symptom:

You need to reprocess from scratch or state became stale/corrupt.

Fix:

Use a clean state file path:

$ honestroles ingest sync --source ashby --source-ref notion --state-file .honestroles/ingest/state-reset.json

Or run with --full-refresh for one execution.

`reliability check` Fails in CI¶

Symptom:

honestroles reliability check --strict exits with code 1.

Cause:

One or more checks are fail, or strict mode escalated a warn status.

Fix:

Run in table mode and remediate by check code:

$ honestroles reliability check --pipeline-config pipeline.toml --plugins plugins.toml --strict --format table

Default artifact path:

dist/reliability/latest/gate_result.json

Override artifact path:

$ honestroles reliability check --pipeline-config pipeline.toml --output-file dist/reliability/custom_gate.json

Reliability Check Code Map¶

Use this mapping for fast remediation:

Code	Typical fix
`ENV_PYTHON_VERSION`	Use Python `>=3.11`.
`ENV_REQUIRED_IMPORTS`	Install package dependencies in the active environment.
`CONFIG_PIPELINE_PARSE`	Run `honestroles config validate --pipeline ...` and fix config schema errors.
`CONFIG_PLUGIN_MANIFEST_PARSE`	Run `honestroles plugins validate --manifest ...` and fix manifest schema/callables.
`INPUT_EXISTS`	Point `[input].path` to a readable parquet file.
`INPUT_SAMPLE_READ`	Verify parquet readability and file permissions.
`INPUT_CANONICAL_CONTRACT`	Fix alias/adapter mappings so canonical fields are populated.
`INPUT_CONTENT_READINESS`	Ensure sampled rows include required content (for example non-null titles).
`OUTPUT_PATH_WRITABLE`	Create/make writable the output parent directory.
`POLICY_MIN_ROWS`	Increase sample/input coverage or lower `min_rows` threshold.
`POLICY_REQUIRED_COLUMNS`	Add aliases/adapter mapping for required policy columns.
`POLICY_NULL_RATE`	Reduce null rates via mapping/cleaning of flagged fields.
`POLICY_FRESHNESS`	Use a valid date column and update source extraction cadence/threshold.

`recommend match` Fails with Candidate Input Error¶

Symptom:

provide exactly one of --candidate-json or --resume-text

Cause:

Both candidate inputs were provided, or neither was provided.

Fix:

$ honestroles recommend match --index-dir dist/recommend/index/<index_id> --candidate-json examples/candidate.json

or

$ honestroles recommend match --index-dir dist/recommend/index/<index_id> --resume-text examples/resume.txt --profile-id jane_doe

`recommend evaluate` Fails Quality Thresholds¶

Symptom:

Exit code 1 with checks such as:
EVAL_PRECISION_AT_10_BELOW_THRESHOLD
EVAL_RECALL_AT_25_BELOW_THRESHOLD

Fix:

Inspect metrics:

$ honestroles recommend evaluate --index-dir dist/recommend/index/<index_id> --golden-set examples/recommend_golden_set.json --format table

Improve matching policy / profile coverage first, then adjust recommend_eval.toml only if needed.

Recommendation Filter Codes¶

With --include-excluded, each excluded row includes deterministic reasons:

FILTER_LOCATION
FILTER_WORK_MODE
FILTER_EMPLOYMENT_TYPE
FILTER_SALARY
FILTER_VISA

Plugin Callable Reference Fails¶

Symptom:

PluginLoadError

Typical causes:

Missing : in module:function
Module import fails
Function name does not exist

Fix:

$ honestroles plugins validate --manifest plugins.toml

Plugin Signature Validation Fails¶

Symptom:

PluginValidationError

Typical causes:

Missing explicit annotations
Wrong context type for plugin kind
Wrong return annotation/type

Fix:

Match one of:

filter: (JobDataset, FilterStageContext) -> JobDataset
label: (JobDataset, LabelStageContext) -> JobDataset
rate: (JobDataset, RateStageContext) -> JobDataset

Plugin Execution Fails¶

Symptom:

PluginExecutionError

Typical causes:

Plugin raised an exception
Plugin returned non-DataFrame result

Fix:

Start with fail_fast = true for immediate failure context.
Add defensive checks in plugin logic.

Stage Execution Fails¶

Symptom:

StageExecutionError

Typical causes:

Invalid data shape for stage operation
Unexpected stage transformation errors

Fix:

Validate source data and schema assumptions.
Inspect diagnostics to identify last successful stage.

Recovery Mode Produces Partial Results¶

Symptom:

Run returns success, but output quality is lower than expected.

Cause:

fail_fast = false allowed continuation after one or more stage/plugin errors.

Fix:

Inspect:

print(run.diagnostics.to_dict().get("non_fatal_errors", []))

Adapter Coercion Warnings Are High¶

Symptom:

diagnostics["input_adapter"]["coercion_errors"] contains high counts.

Cause:

Source values do not match adapter cast expectations (for example non-boolean tokens in a cast = "bool" field, invalid dates for cast = "date_string").

Fix:

Inspect adapter diagnostics and samples:

print(run.diagnostics.to_dict()["input_adapter"]["coercion_errors"])
print(run.diagnostics.to_dict()["input_adapter"]["error_samples"][:5])

Expand adapter field fallbacks and parsing vocab:

[input.adapter.fields.remote]
from = ["remote_flag", "is_remote"]
cast = "bool"
true_values = ["true", "1", "yes", "y", "remote"]
false_values = ["false", "0", "no", "n", "onsite", "on-site"]

Regenerate a draft and compare:

$ honestroles adapter infer --input-parquet data/jobs.parquet --output-file dist/adapters/adapter-draft.toml

`eda dashboard` Fails with Missing Streamlit¶

Symptom:

streamlit is required for 'honestroles eda dashboard'

Cause:

EDA optional dependencies are not installed.

Fix:

$ pip install "honestroles[eda]"

`eda dashboard` Fails with Missing Manifest or Summary¶

Symptom:

artifacts manifest missing

or

artifacts summary missing

Cause:

--artifacts-dir does not point to a completed honestroles eda generate output directory.

Fix:

$ honestroles eda generate --input-parquet jobs.parquet --output-dir dist/eda/latest
$ honestroles eda dashboard --artifacts-dir dist/eda/latest

`eda diff` Fails with Profile Artifact Errors¶

Symptom:

EDA diff requires profile artifacts as inputs

Cause:

--baseline-dir or --candidate-dir points to non-profile artifacts (for example a diff artifact directory).

Fix:

$ honestroles eda generate --input-parquet baseline.parquet --output-dir dist/eda/baseline
$ honestroles eda generate --input-parquet candidate.parquet --output-dir dist/eda/candidate
$ honestroles eda diff --baseline-dir dist/eda/baseline --candidate-dir dist/eda/candidate

`eda gate` Returns Exit Code 1¶

Symptom:

Command exits with code 1.

Cause:

Gate policy failed (P0 findings above threshold, or drift metrics exceeded fail thresholds).

Fix:

Inspect output payload:

$ honestroles eda gate --candidate-dir dist/eda/candidate --baseline-dir dist/eda/baseline --rules-file eda-rules.toml

Review:

failures
warnings
evaluated_rules

Then adjust source extraction/normalization or update thresholds in eda-rules.toml as needed.

Manual Publish Fails with Missing PyPI API Key¶

Symptom:

Missing PyPI API key. Set PYPI_API_KEY (or PYPI_API_TOKEN) in env or .env.

Cause:

scripts/publish_pypi.sh could not find PYPI_API_KEY or PYPI_API_TOKEN.

Fix:

Add PYPI_API_KEY=<pypi-token> to your shell env or .env.
Re-run:

$ bash scripts/publish_pypi.sh

Manual Release Workflow Fails with Missing PyPI Secret¶

Symptom:

Missing PyPI token secret. Set PYPI_API_KEY (or PYPI_API_TOKEN) in repository secrets.

Cause:

GitHub Actions cannot read local .env values.
Neither PYPI_API_KEY nor PYPI_API_TOKEN is set in repository secrets.

Fix:

Add one of these repository secrets: PYPI_API_KEY or PYPI_API_TOKEN.
Re-run the manual Release workflow (workflow_dispatch).

`runs show` Cannot Find a Run¶

Symptom:

run record not found

Cause:

--run-id does not exist under .honestroles/runs/ in the current project directory.

Fix:

List available run IDs:

$ honestroles runs list --limit 20 --format table

Use one of those IDs:

$ honestroles runs show --run-id <run_id>

Coverage Gate Drops Below 100% in CI¶

Symptom:

Coverage failure: total of 98 is less than fail-under=100

Common cause:

Tests rely on optional plotting/runtime dependencies being installed in CI.

Fix:

Run the canonical gate command:

$ PYTHON_BIN=.venv/bin/python bash scripts/run_coverage.sh

Keep tests deterministic by stubbing optional dependencies instead of requiring them for coverage-critical paths.

Common Errors¶

Config Validation Fails¶

doctor Reports fail¶

ingest sync Fails with Invalid source-ref¶

ingest sync Fails for Workable with HTTP 404¶

ingest sync Hits HTTP 429 / Backoff¶

ingest sync / ingest validate Fails in Strict Quality Mode¶

ingest sync Returns Empty Result Set¶

ingest sync-all Manifest Validation Fails¶

Reset Ingestion State¶

reliability check Fails in CI¶

Reliability Check Code Map¶

recommend match Fails with Candidate Input Error¶

recommend evaluate Fails Quality Thresholds¶

Recommendation Filter Codes¶

Plugin Callable Reference Fails¶

Plugin Signature Validation Fails¶

Plugin Execution Fails¶

Stage Execution Fails¶

Recovery Mode Produces Partial Results¶

Adapter Coercion Warnings Are High¶

eda dashboard Fails with Missing Streamlit¶

eda dashboard Fails with Missing Manifest or Summary¶

eda diff Fails with Profile Artifact Errors¶

eda gate Returns Exit Code 1¶

Manual Publish Fails with Missing PyPI API Key¶

Manual Release Workflow Fails with Missing PyPI Secret¶

runs show Cannot Find a Run¶

Coverage Gate Drops Below 100% in CI¶

`doctor` Reports `fail`¶

`ingest sync` Fails with Invalid `source-ref`¶

`ingest sync` Fails for Workable with HTTP 404¶

`ingest sync` Hits HTTP 429 / Backoff¶

`ingest sync` / `ingest validate` Fails in Strict Quality Mode¶

`ingest sync` Returns Empty Result Set¶

`ingest sync-all` Manifest Validation Fails¶

`reliability check` Fails in CI¶

`recommend match` Fails with Candidate Input Error¶

`recommend evaluate` Fails Quality Thresholds¶

`eda dashboard` Fails with Missing Streamlit¶

`eda dashboard` Fails with Missing Manifest or Summary¶

`eda diff` Fails with Profile Artifact Errors¶

`eda gate` Returns Exit Code 1¶

`runs show` Cannot Find a Run¶