> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oasm.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting & FAQ

> Resolve common OASM issues and find answers to frequently asked questions about the platform

This page collects the issues most frequently encountered when running OASM and the diagnostic steps to resolve them. Where a fix depends on your environment, the guidance points at the right place to look — worker logs, the Core API health endpoint, or the relevant settings page — rather than prescribing a single command.

If an issue is not covered here, start with the [audit log](/audit-log) to see what happened and when, then check the relevant service logs in your deployment.

## Where to look first

Before diving into a specific issue, gather the basics — most problems are visible in one of these four places:

1. **Service status** — `docker compose ps` shows which containers are running; the [Deployment](/deployment) port reference tells you what each service should be listening on.
2. **API health** — run the health check shown in the [Deployment](/deployment) guide. If the API is not responding, nothing downstream (console, workers, jobs) can work properly.
3. **Service logs** — `docker compose logs <service>` for `core-api`, `oasm-worker`, and `migration` surfaces auth errors, tool failures, and startup problems. Worker logs are the first place to look for job execution issues.
4. **Audit log** — the [audit log](/audit-log) records workspace activity, including failed attempts, so you can see who did what and what failed.

## Common issues

<Accordion title="The console is unreachable after docker compose up">
  Verify the stack came up in order:

  1. Check the Core API health endpoint (see the health check in the [Deployment](/deployment) guide). If it does not respond, the API is not ready and the console (which depends on `core-api` being healthy) will not come up.
  2. Confirm the `migration` service completed before the API started — migrations must finish before the API can serve.
  3. Check port bindings — `6276` (console web UI and `/api` proxy) and `16276` (gRPC passthrough) must be free on the host and published by compose. The API REST is also reachable through the console on `6276`.
  4. Inspect `docker compose ps` and the logs of `console` and `core-api` for startup errors.

  See [Deployment](/deployment) for the full service and port reference.
</Accordion>

<Accordion title="No workers available, or jobs stay stuck at 'Queued'">
  A job stays **Queued** when no worker has claimed it yet. Check, in order:

  1. Is the worker container running? `docker compose ps` should show `oasm-worker` up.
  2. Are the worker connection settings correct? Workers authenticate with the workspace API key; a mismatch silently prevents job claims. See the worker connection settings described in the [Deployment](/deployment) guide.
  3. What do the worker logs say? Connection failures, auth errors, and tool errors all appear there.
  4. Is the worker's scope correct? A **Workspace**-scoped worker only claims jobs for its own workspace; a **Global** worker claims jobs across workspaces.

  Job statuses — **Queued**, **Running**, **Completed**, **Failed**, or **Cancelled** — are visible in the [job registry](/jobs). See [Workers](/worker), and check the worker connection settings described in the [Deployment](/deployment) guide.
</Accordion>

<Accordion title="Discovery completes but no assets appear">
  The scan ran, but nothing landed in the asset inventory. Work through these:

  1. **Tool install status** — check whether the tools a job needs are **Built-in** or **Installed**. A job whose tool is not installed produces no results. The tool list and data source mapping are on the [Tools](/tools) page.
  2. **Data source mapping** — some tools report services rather than plain host assets (for example, results from HTTP probing or screenshots). A service-oriented result appears under services, not as a plain host asset.
  3. **Workspace configs** — open **Settings → General → Configs**. If **Asset discovery** is off, discovery jobs are not scheduled for targets; if **Auto enable assets** is off, newly discovered assets are not enabled for further scanning and processing. See [Workspaces](/workspace).

  Also confirm the job actually completed — a **Failed** job merges nothing into the inventory.
</Accordion>

<Accordion title="Login issues or no way to create the first account">
  On a fresh deployment, the initial admin account is bootstrapped through the **`/init-admin`** route — open `http://localhost:6276/init-admin` before the first sign-in. The first account created this way receives **admin** privileges automatically.

  For existing deployments, new users join workspaces through invitations. Pending invitations grant no access until accepted — check the **Invitations** tab for resend or cancel actions. See [Onboarding](/onboard) and [Members](/members).
</Accordion>

<Accordion title="An API key stops working">
  API keys are **workspace-scoped**: a key only authenticates against its own workspace. If the key was rotated, the old key was **invalidated immediately** — every consumer (workers, MCP clients, API scripts) must be updated to the new key. Make sure every consumer is configured with the current key. See [API keys](/api-keys).
</Accordion>

<Accordion title="Notifications are not arriving">
  Notifications only fire for specific events, so first confirm the event actually occurred. Then check:

  1. **Integration status** — the [Integrations](/integrations) page shows whether each connection (Slack, Telegram, Webhook, and others) is healthy.
  2. **Notification configuration** — the [Notifications](/notifications) page controls which events and severities produce notifications; a filter that excludes the event suppresses the alert.
  3. **Notification types** — notifications fire for specific moments in the pipeline, such as a new asset being discovered or a new vulnerability being found; an event that never occurs will never notify.
</Accordion>

<Accordion title="Port conflicts between development and Docker">
  The platform uses different ports depending on how it runs:

  * **Production (oasm-docker)**: web UI on **6276** (nginx serves the console and forwards API traffic), with the gRPC passthrough on **16276**.
  * **Local development (open-asm source tree)**: console served by Vite on **5173**, API on **6276**.

  If a port is already in use, change the host-side mapping in the compose file (for example `3001:80`) or stop the process holding the port. The API port **6276** is the same in both modes, so conflicts there usually mean two instances are running.
</Accordion>

<Accordion title="Scans are slow">
  Throughput depends on three levers:

  1. **Worker concurrency** — how many jobs a single worker executes in parallel (default 10). Raise it on capable hosts.
  2. **Worker count** — workers scale horizontally; add replicas to process more jobs at once. See [Deployment](/deployment).
  3. **Scope size** — the number of targets, assets, and enabled discovery categories determines total work. Narrow scope or reduce categories for faster cycles.

  Also confirm jobs are actually running in parallel — if everything queues behind a single Queued job, a worker is probably not claiming work (see the stuck-jobs item above).
</Accordion>

<Accordion title="SSL / TLS certificate issues on assets">
  Certificate data is collected during discovery and surfaced on assets. If certificates look wrong or missing:

  1. Confirm the discovery category that collects TLS data completed for the affected assets.
  2. Check the **TLS Statistics** section on the dashboard, which summarizes certificate coverage and age across the inventory.
  3. Re-run discovery for the affected target if the certificate was recently issued or rotated — certificate data refreshes only when a job merges new results.

  See [Dashboard](/dashboard) and [Assets](/asset).
</Accordion>

<Accordion title="General debugging — who did what, and what version is running">
  * **Audit log** — the [audit log](/audit-log) records workspace activity (for example **Created API key**, **Revoked API key**, **Deleted scan target**) including failed attempts. Filter by **Outcome = Failure** to surface repeated failures that indicate misconfiguration or abuse.
  * **Version and health** — open **Settings → About**. The page shows the platform version and a status line such as **Platform is up to date**. The API health check described in the [Deployment](/deployment) guide confirms the service is responsive.
  * **Search** — use [search](/search) to locate assets, vulnerabilities, and issues by query across the workspace.
  * **Reports** — the [Reports](/reports) page summarizes the pipeline's output; a report with empty or stale data points back to job health rather than to reporting itself.
</Accordion>

## FAQ

<Accordion title="What license is OASM released under?">
  OASM is open source under **GPL-3.0**. You can run it, modify it, and deploy it on your own infrastructure under the terms of that license.
</Accordion>

<Accordion title="What is the difference between self-hosted and OASM Cloud?">
  **Self-hosted** runs the full stack on your own infrastructure (see [Deployment](/deployment)) — you control data, networking, and workers. **OASM Cloud** is the hosted offering; some integrations accept a cloud API key to connect to cloud services. The platform itself is the same — the difference is where it runs and who operates it.
</Accordion>

<Accordion title="How do SDKs fit in?">
  OASM exposes an API (documented in the API reference) plus official client libraries, so anything you can do from the console you can automate. SDKs and the MCP server both authenticate with the workspace API key. See [API keys](/api-keys) and the [MCP Server](/settings/mcp).
</Accordion>

<Accordion title="Is OASM really free?">
  Yes — OASM is free and open source under GPL-3.0. There is no fee to run the platform itself; you pay only for the infrastructure it runs on.
</Accordion>

<Accordion title="How do I upgrade an existing deployment?">
  Pull the new images and run `docker compose up -d` again. The `migration` service runs TypeORM migrations automatically before the API starts, so schema changes apply in order. Watch the `migration` service log to confirm migrations completed, and check release notes for manual steps before upgrading major versions. See [Deployment](/deployment).
</Accordion>

<Accordion title="Can I run OASM in development alongside the Docker stack?">
  Yes, but not on the same ports. In production (`oasm-docker`) the console binds **6276** and the API is reachable on **6276** as well; in the `open-asm` dev source tree the compose console binds **3000**, the Vite dev server serves on **5173**, and the API stays on **6276**. Run one mode at a time, or change host port mappings in compose to avoid conflicts. See the [Developer guide](/developer-guide) and [Deployment](/deployment).
</Accordion>

<Accordion title="Where do I find the version number?">
  Open **Settings → About**. The page shows the platform version and a status line such as **Platform is up to date**, which confirms your instance is running a current release.
</Accordion>

## Related

<Card icon="rocket" title="Deployment" horizontal href="/deployment">
  Deploy the full stack with Docker Compose
</Card>

<Card icon="scroll-text" title="Audit log" horizontal href="/audit-log">
  Investigate who did what, and when
</Card>

<Card icon="cpu" title="Workers" horizontal href="/worker">
  Understand the execution layer behind job statuses
</Card>

<Card icon="plug" title="Integrations" horizontal href="/integrations">
  Check notification and ticketing connections
</Card>