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

# Troubleshooting · ByteSpike × DOSIA

> One-stop troubleshooting for employees / admins — install / SSO / model permissions / balance / abuse / emergency-response SOP all in one place.

<Note>
  **When this applies**: you got stuck, hit an error, or saw an unexpected empty state at some step of [Employee onboarding](./employee-onboarding) or the [Admin operations runbook](./admin-operations). The page below is organized by role (Tabs) + scenario (AccordionGroup) — pick your role first, then find your symptom.
</Note>

<Tabs>
  <Tab title="Employee view">
    ## Install / launch

    <AccordionGroup>
      <Accordion title="First launch reports &#x22;file damaged&#x22; / &#x22;from unidentified developer&#x22;">
        macOS Gatekeeper is blocking the un-notarized dmg — run this in Terminal:

        ```bash theme={null}
        xattr -cr /Applications/DOSIA.app
        ```

        Then relaunch DOSIA.
      </Accordion>

      <Accordion title="No &#x22;ByteSpike Shared&#x22; provider after DOSIA launches">
        Check in order (most common first):

        1. **Enterprise mode not switched on** → go to **Settings → Deploy Mode**, confirm it shows "Enterprise" not "Personal"
        2. **Enterprise service URL typo** → same page, double-check the URL — copy the full string the admin gave you (default `http://122.51.0.230:3012`)
        3. **Admin hasn't published the token** → in DOSIA Settings → **ByteSpike tab**, the top should show a green bar "Configured · auto-fetched on employee launch"; if missing, ask admin to publish again
        4. **Employee lark OAuth expired** → DOSIA **Settings → My Account**, check SSO status; if expired, sign out + sign back in
        5. None of the above work → screenshot + @ByteSpike Ops in the lark group
      </Accordion>

      <Accordion title="After lark authorization DOSIA freezes / loops on login">
        Clear local auth state and restart:

        ```bash theme={null}
        rm -rf ~/Library/Application\ Support/DOSIA/auth
        ```

        Relaunch DOSIA to trigger a fresh OAuth. If still broken, screenshot + DM the admin on lark.
      </Accordion>
    </AccordionGroup>

    ## Model permissions

    <AccordionGroup>
      <Accordion title="Chat box says &#x22;permission denied&#x22; / &#x22;model not allowed&#x22;">
        Admin hasn't granted your group access to that model. Ask admin to go to [llm.bytespike.ai/admin](https://llm.bytespike.ai/admin) → **Users** → your account → **Allowed Models** and tick the matching model group.
      </Accordion>

      <Accordion title="Test connection shows modelCount = 0 (DOSIA config panel)">
        DOSIA Settings → ByteSpike tab, "Test connection" returns `modelCount: 0`:

        1. Previously W1/W2 fixed `/admin/available-models` 401 → it now uses `/me/available-models`, **a normal user should see ≥ 1**
        2. Still 0 → admin hasn't bound the user to a group. Per the previous accordion, ask admin to handle.
        3. The token itself has an issue → see below "Test connection returns 401"
      </Accordion>

      <Accordion title="Image recognition errors (vision)">
        The selected model doesn't have vision capability. At [console.bytespike.ai/zh/models](https://console.bytespike.ai/zh/models) "Model library", find ones tagged with vision (e.g. Claude Sonnet 4.6, GPT-5-4, Gemini 3.5 Flash), switch DOSIA to one of those and retry.
      </Accordion>

      <Accordion title="Image / video generation tab is missing">
        Multimodal capability is granted separately (independent of text models). Admin should go to [llm.bytespike.ai/admin](https://llm.bytespike.ai/admin) → your group → add `image` / `video` capability, and DOSIA will pick up the tool after a restart.
      </Accordion>
    </AccordionGroup>

    ## Balance / testing

    <AccordionGroup>
      <Accordion title="Chat box says &#x22;insufficient balance&#x22;">
        The org wallet ran out. Screenshot + ask admin — once admin tops up at [console.bytespike.ai/billing](https://console.bytespike.ai/billing) it recovers immediately.
      </Accordion>

      <Accordion title="Test connection returns 401 (token invalid)">
        Token expired. Go to [console.bytespike.ai/keys](https://console.bytespike.ai/keys), create a new key, paste it into DOSIA Settings → ByteSpike tab → re-test connection.

        If a new key still 401s → ask admin to check your user status (you may have been suspended).
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Admin view">
    ## Emergency-response SOP

    <AccordionGroup>
      <Accordion title="Balance crash (suspected abuse)">
        <Steps>
          <Step title="Check audit log">
            [llm.bytespike.ai/admin](https://llm.bytespike.ai/admin) → **Audit log** → sort `created_at desc` → look for anomalously high-frequency `admin.api_key.*` or unusual calls.
          </Step>

          <Step title="Locate the suspicious api_key">
            **Usage** → `group_by api_key` → find keys with abnormal 24h spend.
          </Step>

          <Step title="Revoke immediately">
            **User management** → click the user → click the key → **Revoke**. The revoked key returns 401 instantly — no further cost.
          </Step>

          <Step title="Postmortem">
            If the employee leaked the key: ask them to rotate + educate on security. If it's an admin mis-operation: trace it back via audit log + refund the employee's quota.
          </Step>
        </Steps>
      </Accordion>

      <Accordion title="A model is temporarily unavailable (elevated 5xx for one model)">
        <Steps>
          <Step title="Confirm the incident">
            **Model groups** → find the group serving the affected model → look at schedulable / health status.
          </Step>

          <Step title="Temporarily take it offline">
            On the group detail page → set the affected entry `schedulable=false`. The router stops sending traffic to it immediately and auto-falls-back within the same group.
          </Step>

          <Step title="After it recovers">
            Switch back to `schedulable=true`. Requests during the window were already absorbed within the same group — users don't notice (unless the entire group was unavailable).
          </Step>
        </Steps>
      </Accordion>

      <Accordion title="An employee abuses the system (high-frequency calls / draining balance)">
        Path 1 · **Rate-limit**: **User management** → click employee → **Concurrency** down to 1 + **RPM** down to 6 → save. Their subsequent calls are blocked with 429.

        Path 2 · **Suspend account**: **User management** → click employee → **Status**: active → disabled → save. Their keys 401 instantly and DOSIA also can't SSO.

        Path 3 · **Adjust multiplier** (for a specific model): **Model groups** → bump that group's multiplier from 1.0 to 5.0 — global effect, use carefully.
      </Accordion>
    </AccordionGroup>

    ## Handling employee feedback

    <AccordionGroup>
      <Accordion title="Employee reports &#x22;no available models&#x22;">
        The most common cause is the employee **hasn't been granted any group** (default 0 for new employees). Per [admin-operations § 2](./admin-operations#2-grant-employees-model-permissions-core-operations-action), bulk-tick all 11 public groups for the employee.

        If after bulk-grant the employee still reports it — ask them to sign out of DOSIA and sign back in (clears the token cache).
      </Accordion>

      <Accordion title="Employee reports &#x22;ByteSpike Shared&#x22; provider does not appear">
        Same symptom as an onboarding-stuck employee. Have them follow "Employee view → Install / launch" second accordion's 5 checks. Most commonly it's an **enterprise service URL typo** or the **admin token hasn't been published**.
      </Accordion>

      <Accordion title="Employee reports test-connection modelCount = 0">
        Check whether admin bound the employee to a group: [llm.bytespike.ai/admin](https://llm.bytespike.ai/admin) → User management → click employee → "Allowed Models" tab and look at ticks. If all empty → bulk-tick the 11 public groups → employee restarts DOSIA.
      </Accordion>

      <Accordion title="Got admin.api_key.revoke in notification center but I did not revoke it">
        A platform admin (e.g. ops teammate) might have revoked. In the audit log filter `action=admin.api_key.revoke` → look at the actor. If it's a mis-op, ask them to roll back + reissue the employee's key. If it's a legitimate abuse-response action, leave it.
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

## Still stuck?

* **Employees**: @ByteSpike Ops in the lark group
* **Admins / OP**: DM W1 on lark, or directly SSH into lisahost (`38.78.146.204`) + the 122.51 backend to investigate
* **Integration issues**: [GitHub Issues](https://github.com/leave1206/bytespike-website/issues) (internal repo — login required)