Help

Quick answers to common questions. For a full walkthrough of the web UI, see the User Guide. For config.yaml/Admin-page settings, see docs/CONFIGURATION.md in the repo. For installing the service itself, see packaging/INSTALL.md in the repo.

"I can't log in"

The login identifier is your email address, not a username. If you don't have an account, ask an Admin to create one (or bulk-import a batch via the Excel template on /admin/users). There's no self-service password reset today -- an Admin needs to recreate your account to change your password (see the User Guide).

"The Analyze with AI button doesn't appear on my run"

Two things both have to be true (see AI Analysis):

1. An Admin has set up the shared LLM configuration at /admin/llm-config.
2. Your account specifically has been granted AI-analysis permission by an Admin, on the Users page. This is off by default for every account except the very first bootstrap admin -- even other Admin accounts don't have it automatically.

Also, the button never appears on Excel-target runs (there's no downstream QAD system to spot-check against). It does appear on dry-run runs -- there, the AI is given the deterministic dry-run preview (parse/transform issue counts and error frequency) instead of a load precheck.

"I don't see an AI Address Analysis section on my run"

Two things both have to be true (see Runs):

1. The map itself opts in -- at least one Field Map row has Field Type set to address.
2. An Admin has turned on Enable AI address analysis under Admin: System Configuration. Off by default, independent of the per-map opt-in.

If either is off, no section appears and no address_analysis.* files are written for that run -- this is by design, not a bug. Unlike the "Analyze with AI" button, this doesn't require any per-user permission and isn't gated on the map's target type.

"My workbook won't compile"

The compile error report lists every problem it found in one pass (not just the first one) -- check for: a Field Map row referencing a source column that isn't in the Source tab, a formula referencing a column name that doesn't exist, a Xref tab name that doesn't match what a Field Map row references, or a missing required Source/Target metadata cell. Fix everything listed and re-upload; a successful compile always creates a new version rather than overwriting the last one, so a broken re-upload attempt never damages an already-working version.

"My workbook won't compile: 'no successful extraction found for profile family ...'"

A Field Map xref rule can source its lookup table from an extraction profile's latest successful normalized dataset instead of an in-workbook xref tab (Extraction Profile Family / Extraction Dataset / Extraction Key Column / Extraction Value Column -- see Maps). A Rules tab referential check hits the same error for the same reason (its Extraction Profile Family / Extraction Dataset / Lookup Column columns resolve against the identical extraction data). Either way, this error means that profile family has never had a succeeded extraction run yet -- go to Extractions and run it at least once, then recompile the map. The table/lookup set is resolved and baked in at compile time from whichever extraction most recently succeeded, so a later extraction run doesn't retroactively change an already-compiled map version -- recompile to pick up newer data.

"I don't see a Data-quality rules section on my run"

That section only appears when the compiled map has a Rules tab (see Maps) -- unlike AI address analysis, there's no admin toggle to check; if a map has no Rules tab, every run of it writes no rules_report.* files and shows no section, by design. If you expected rules to be there and they aren't, check whether this map version was produced by Edit this version in the browser -- the Map Editor doesn't carry a Rules tab forward into the new version it saves (see the next question).

"My map's data-quality rules disappeared after I edited it in the browser"

The browser Map Editor (Edit this version) doesn't expose or preserve the Rules tab -- every version it saves has an empty rules list, even if the version you started from had rules. This is a current limitation, not a bug in your data. To change a map's Rules tab, re-upload the workbook (via Maps > upload) with the Rules tab you want; that produces a new, workbook-sourced version that keeps its rules.

"Why does my run's row count not match what I expected?"

If a Rules-tab rule has On Fail: drop, any record that fails it is removed the same way a transform-stage issue would be -- via the map's configured failure policy (abort on first error, skip and continue, or a fail-rate threshold). Check the run's Data-quality rules section for which rule dropped which rows, and failed_rows.csv for the removed records themselves. On Fail: warn rules never remove rows -- they only add an entry to the report.

"Why does my map show a 'drift' badge?"

A map version gets a drift badge/banner (on /maps and on that version's own detail page) when its provenance is a browser edit rather than a workbook upload -- internally, that version's source_kind is "web_edit" instead of "workbook" (see "Editing a map in the browser" under Maps). It just means: this version was produced by someone using the Edit this version page, so it no longer matches any .xlsx file on disk -- if you (or someone else) later re-upload the original workbook, that re-upload would not include whatever was changed in the browser. It's informational, not an error -- the map still works exactly as compiled. To clear it, upload a workbook (via /maps/compile) that already contains the edits you want; that produces a new, workbook-sourced version without the badge.

"A REST or QXtend run failed with an authentication error"

Both adapters deliberately fail fast and stop retrying on a 401/403 (or, for QXtend, a response that looks auth-related) -- every remaining not-yet-attempted record in that run is marked not-sent with an explicit message, rather than being retried, because replaying bad credentials against QAD risks locking the account. Check the configured credentials (Admin > System Configuration for QAD REST/QXtend, or the referenced environment variables) and re-run once they're fixed.

"Where do I find a run's raw results, logs, or the AI's tool-call transcript?"

Every run gets its own folder under storage.data_dir/runs/<run_id>/: parse/transform issues, load results, a downloadable re-runnable file for any skipped/failed rows, and (when AI analysis ran) verification_report.md plus the full tool_call_log.json of everything the AI queried.

"I changed a QAD REST/QXtend setting on System Configuration but nothing happened"

Changes there take effect on the next run launched after saving -- an already-running run keeps using whatever configuration it started with. If it still looks wrong, double check you saved the System Configuration form (not config.yaml, which is now only a fallback used to seed the database on a install's very first startup -- see docs/CONFIGURATION.md in the repo).

"My extraction failed a probe / says the host doesn't match this profile"

Extraction profiles are pinned to a specific, verified source-host shape (see Extractions) -- a failed probe means the source host doesn't look the way this profile version expects (wrong Progress/QAD release, a missing install path, ...), and the extraction deliberately stops there rather than pushing or running anything against an unverified host. The extraction detail page lists exactly which probe(s) failed and what they saw. If this client's source genuinely differs from the shared base profile, ask whoever maintains extraction profiles about adding a client overlay rather than editing the base profile itself.

"I added a source connection but can't launch an extraction against it"

A newly-added source connection has no host key fingerprint pinned yet -- click Test Connection on /admin/source-connections first (see Admin: Source Connections). Also double-check the connection is enabled; only enabled connections show up on the Launch Extraction form.

"My comparison failed instead of showing a diff"

Dataset comparisons (see Dataset Comparisons) deliberately fail loudly rather than produce a partial or silently-wrong diff: a missing source file, a duplicate key on the chosen key column(s) (unless you set On duplicate key to "warn"), or a column-set mismatch between the two sides (unless you set On column-set mismatch to "compare shared columns only"). The comparison detail page shows the specific error -- fix the underlying data issue, or relax the matching option that's causing the failure, and resubmit.

"My comparison shows changes on a column I don't care about"

Add that column name to Ignore columns (comma-separated) on the launch form, or via --key/options on etlp compare submit -- common for timestamp-like columns (last_seen, updated_at) that always differ between two pulls even when nothing meaningful changed. If values only differ in formatting (e.g. 1.50 vs 1.5, or a date written two different ways) rather than content, that's usually solved automatically when both sides deliver to the same compiled map -- comparisons then type-aware-compare number/date columns per that map's source contract instead of comparing raw strings.

"I set up a schedule but no extraction is firing"

Check /admin/schedules -- a paused schedule (button says Resume) never fires until you resume it. If it's enabled, a schedule fires "every N minutes" from when it was created or last fired, not at a fixed clock time (see Admin: Scheduled Extraction Runs), so a newly created schedule fires on the very next check rather than waiting a full interval. Also check whether the schedule's previous extraction is still queued/running on /extractions -- a schedule intentionally skips firing again while its last run is still in flight, rather than piling up duplicate work.

"I can't edit cells on the Build Order page"

Editing (plus Add Row, Delete, and Import) is Admin-only -- Consultants and Viewers see a read-only grid. If you are an Admin and a cell edit flashes red, hover it: the tooltip shows why the value was rejected (e.g. a Status outside Not Started / In Progress / Complete / N/A, or a non-numeric Help Page).

"My Build Order import was rejected"

An import is all-or-nothing: one bad row rejects the whole file and nothing changes. The error list names each offending row -- the usual causes are a malformed Build Order code (must look like A01.005: capital letter, two digits, period, three digits), a duplicate code inside the file, a changed header row, or a blank Module/Group/Menu Name. Start from a fresh Export to Excel and edit that file rather than building a workbook from scratch -- the export's column layout is exactly what import expects.

"Rows I deleted in Excel are still on the Build Order page"

That's by design. Import updates matching codes and inserts new ones, but never deletes -- rows missing from your file are listed in the import report with a per-row Delete button, so removals are always an explicit click rather than a side effect of a stale spreadsheet.

Still stuck?

Check the service's log (journalctl -u etl-prophet -f on a systemd install) for the underlying error, and the run folder's artifacts described above for anything run-specific.