Troubleshooting

Report a scan problem

Scanned a repo and the diagram is missing a service, drew a flow backwards, came out empty, or the CLI failed on your monorepo? That feedback directly improves the scanner — please report it.

Open an issue at github.com/DataParade-io/dataparade-cli/issues  (or use Contact) and include:

• CLI version and OS — npx @dataparade/cli --version.
• The stack — languages and frameworks in the repo, and rough size (file count or metadata from dataflow.json).
• Expected vs actual — the service or flow you expected and what the scan produced. A screenshot of the diagram or the relevant dataflow.json nodes/edges helps. dataflow.json contains component names and file paths but no source snippets — still, redact anything sensitive before sharing.
• For CLI errors — the console output, including anything printed on stderr.
• For AI enrichment issues — the --ai-verbose summary if you can share it.
• A reproduction if possible — a link to a public repo that shows the problem is the fastest path to a fix.

Requests for new languages or frameworks are welcome in the same tracker.

Workspace scan quota

If Create assessment blocks a Git or ZIP hosted scan, Workspace → Usage shows no scans or tokens remaining, or the CLI exits before scanning:

• Open Workspace scan quotas for limits, deductions, and pre-scan estimates.
• Failed scans do not use a completed-scan slot — only successful completions deduct quota.
• CLI with workspace key but no AI (SCAN_AI_INFERENCE off) does not use quota at all; you do not need a key for structural-only runs.
• CLI quota block — message starts with [scan] workspace quota: (for example No scan slots remaining in this workspace.). That means preflight was denied, not that the scan crashed mid-run.
• Hosted pre-start messages are estimates; hosted token use is applied when the job completes. CLI platform AI bills tokens per infer task during the scan.
• Check Workspace → Usage and Activity (scan.quota_blocked, scan.completed, scan.failed).
• To raise limits, contact your workspace owner or administrator (no self-serve upgrade in the app today).

CLI upload to dashboard

If upload or auto-upload after scan fails:

• Confirm DATAPARADE_API_BASE_URL points at your backend (for local dev: http://localhost:3000).
• For local dev, set DATAPARADE_APP_URL (frontend) if preview links should point at localhost (http://localhost:3001).
• Auto-upload is skipped when --skip-auto-upload or DATAPARADE_SKIP_AUTO_UPLOAD is set.
• Upload does not require scan quota; quota messages apply only to platform AI scans.

With a workspace API key (DATAPARADE_WORKSPACE_API_KEY or --workspace-api-key):

• Confirm the key is set and not revoked — Workspace → Access keys (owners only).
• Preview link format: /dashboard?importDraft=<draftId>.
• If the modal does not load, sign in to the workspace that owns the draft and ensure your role is owner or editor.

Without a workspace API key (anonymous preview + sign-up flow):

• Preview link format: /preview/cli/<claimToken>.
• Open the link, sign up, then the dashboard should open the import preview modal automatically.
• If the preview does not appear after sign-up, sign out and open the original link again while signed in, or run upload on your dataflow.json.
• Anonymous preview links expire after 7 days if not claimed.

See Upload to dashboard.

Common Import Issues

• Invalid dataflow.json schema
• Uploading non-JSON files in CLI import
• Uploading non-ZIP files in local scan
• Incomplete scan job or canceled upload — review Scan arguments and Environment variables

Common Modeling Issues

• Missing node properties after type changes
• Style changes not saved due to unsaved state
• Legacy type values appearing in older diagrams (see Node Types for current canonical values)

What To Check

• Browser validation errors in the import dialog
• Backend logs for import/scan services
• Current canonical options configured in the platform — see Node Types and Node Properties

Still stuck? See Contact.