Skip to main content

Troubleshooting

Common Issues​

"Email verification required" on login​

Your platform admin needs to configure SMTP first (Settings > Integrations), then enable email verification. If you're the admin and stuck, the verification toggle is off by default — you can sign up without it.

Worker shows "Not profiled" or "Profile failed"​

The hardware benchmark container may not be in your registry. Ask your admin to build and push it:

cd CORE/DockerContainers/HardwareBenchmark
./build-and-push.sh latest push

Workflow fails with "scan status is rejected"​

In SaaS mode, containers are security-scanned. A rejected node has critical CVE vulnerabilities. Check the scan report in the Workflow Builder edit modal and update the container image.

Worker not appearing in Dashboard​

Remote workers must go through the enrollment flow (Add Worker button). Workers that connect without enrollment are rejected. Check if the enrollment token is valid and not expired.

"0s" completion time in System Health​

Tasks completed without calling report_started. This is fixed in newer worker versions — update your worker binary.

Files won't upload — storage limit reached​

Your plan's storage quota is full. Delete unused files or upgrade your plan in Dashboard > Billing.

Emails aren't being delivered (signup verification, invites, receipts)​

Platform email goes through whatever SMTP provider is saved in Settings → Integrations → Email. Things to check:

  1. Provider configured? The page's "Send Test Email" button is the fastest signal — if a test send fails, the same problem affects every triggered email. The error returned from Postmark / your SMTP host shows up inline.
  2. Templates seeded? Path-A sends (welcome, payment-received, usage alerts, scheduler notifications) need the email-templates MinIO bucket populated with the 24 React Email .tsx files. The bootstrap script (CORE/startup/start-main-server.sh) seeds it; if you bypassed that, run mc cp of the templates from CORE/DockerContainers/ReactEmail/default-templates/ to local/email-templates/.
  3. Audit log signal. EMAIL_TEMPLATE_MISSING events in Dashboard → Logs → Audit are the regression flag — every missed send writes one. Zero entries means the pipeline is healthy.
  4. Bounces. Postmark posts bounce notifications to /webhooks/postmark/bounce; bounced users are auto-flagged after 3 bounces in 30 days. Check Dashboard → Logs → Audit for POSTMARK_BOUNCE_RECEIVED.

Dark mode didn't follow me to another MOD surface​

Light/dark choice is stored in a parent-domain cookie (mod_theme) plus per-app localStorage. If a subdomain isn't flipping with the rest, the cookie probably didn't make it across because the browser is treating the subdomains as cross-site (e.g. third-party-cookie blocking, or you're on localhost where parent-domain cookies don't apply). Re-toggle the theme on the subdomain that's stuck.

Diagnosing over the API​

When a run misbehaves, the API gives you the raw status without the UI in the way:

BASE=https://dev-api.modtechlabs.com

# Exchange your sk_ key for a Bearer token (see /api-reference#authentication)
TOKEN=$(curl -s -X POST "$BASE/api-keys/token" -H "Content-Type: application/json" \
  -d '{"api_key": "sk_your_key_here"}' | jq -r .access_token)
AUTH="Authorization: Bearer $TOKEN"

# Why is a run stuck / what failed? -> status + error detail
curl -s "$BASE/workflows/workflow-runs/<run_id>" -H "$AUTH" | jq '{status, error_message}'

# Live progress detail for a running job
curl -s "$BASE/workflows/workflow-runs/<run_id>/progress" -H "$AUTH"

# Cancel a wedged run
curl -s -X POST "$BASE/workflows/workflow-runs/<run_id>/cancel" -H "$AUTH"

# Is the node registered / which hardware variants built?
curl -s "$BASE/node_definitions/" -H "$AUTH" | jq '.[] | {name, gpu_variants}'

# Confirm you're authenticated as who you think you are
curl -s "$BASE/me" -H "$AUTH" | jq '{email, tenant_id}'

The interactive Swagger explorer lets you run these (and authorize once) from the browser.

Getting Help​

  • Email: support@modtechlabs.com
  • API Docs: https://your-api-url/docs (Swagger UI)
  • Status Page: Check if the platform is under maintenance