PSA/docs/extensions/extension-system-troubleshooting.md

Skill: Extension System Troubleshooting (Alga PSA)

Summary

Guided playbook for diagnosing and fixing Alga PSA extension UI delivery when the iframe shows a spinner or {"error":"not_installed"}. Captures the fixes from the most recent runner/host changes so future incidents can be resolved quickly.

Tags

extensions runner docker minio ui

When to Use

• Extension iframe in MSP app stays on “Starting extension / Loading extension UI…”
• Runner logs show verify_archive fetch failed, strict validation on and tenant resolution failed, or 404s for bundle assets.
• After publishing/installing an extension locally and the UI never loads.

Pre-flight Checklist

• Local docker stack is up (docker compose -f docker-compose.runner-dev.yml up and supporting services).
• Extension is installed (alga extensions list should show status enabled).
• You have access to the .env.runner used by the runner container.

Diagnostic & Fix Flow

1. Verify Runner Configuration

docker logs --tail 20 alga_extension_runner

• Confirm BUNDLE_STORE_BASE points at http://host.docker.internal:9000/extensions.
• If it shows 4569/extensions, restart with:

RUNNER_BUNDLE_STORE_BASE=http://host.docker.internal:9000/extensions \
  docker compose -f docker-compose.runner-dev.yml up --build -d extension-runner

2. Check Bundle Fetch

• Watch for verify archive fetch failed or 404s; if present, the runner can’t locate bundle.tar.zst.
• Ensure MinIO has the tenant-scoped path:

mc ls local/extensions/tenants/<tenant-id>/extensions/<ext-id>/sha256/<hash>/

3. Confirm Install Metadata

node scripts/dev-install-extension.mjs --info <extension-id>

• Make sure content_hash is populated and matches the bundle in MinIO.
• If missing, re-run alga publish ... and alga extensions install ....

4. Tenant Context Handling

• Runner now caches tenant hints; requests without x-tenant-id succeed if the iframe includes ?tenant=<id>&extensionId=<id>.
• In the MSP app, ensure buildExtUiSrc(...) emits both query params (this is handled automatically after commit HEAD).

5. Frontend Spinner

• The Docker iframe uses a hard stop gap: it toggles loading state on iframe onLoad or after 1.5 s.
• If the spinner persists:
  1. Open Chrome DevTools MCP page list.
  2. Navigate to http://localhost:8085/ext-ui/<ext-id>/<hash>/index.html?tenant=<tenant>.
  3. Verify main.js loads (should return 200 OK).
  4. Look for console errors in the iframe; if none, the iframe should render the Hello World page.

6. Runner Strict Validation

• Environment variable EXT_STATIC_STRICT_VALIDATION=false relaxes tenant enforcement for local dev.
• For CI/production, keep it true and ensure host sets x-tenant-id before shipping.

Quick Reference Commands

# Restart runner with correct bundle store and strict validation disabled
RUNNER_BUNDLE_STORE_BASE=http://host.docker.internal:9000/extensions \
EXT_STATIC_STRICT_VALIDATION=false \
docker compose -f docker-compose.runner-dev.yml up --build -d extension-runner

# Tail runner logs
docker logs -f alga_extension_runner

# Fetch extension UI (verify index + assets)
curl -I "http://localhost:8085/ext-ui/<ext-id>/<hash>/index.html?tenant=<tenant>"
curl -I "http://localhost:8085/ext-ui/<ext-id>/<hash>/main.js"

Notes

• The iframe URL builder now appends extensionId to queries; ensure any custom consumers follow the same pattern.
• Browser testing via Chrome DevTools MCP requires pointing at the runner port (8085) and supplying the tenant query manually.
• For persistent issues, re-run npx vitest run ee/server/src/lib/extensions/__tests__/assets/url.shared.test.ts to confirm URL builder behaviour.