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

# Usage and troubleshooting

> Inspect gateway usage and resolve sign-in, project, connector, remote, schedule, and Git problems.

export const ScreenshotCrop = ({src, alt, width, height, x = 0, y = 0, cropWidth = width, cropHeight = height, maxWidth = "100%"}) => <div className="not-prose" style={{
  position: "relative",
  overflow: "hidden",
  width: "100%",
  maxWidth,
  margin: "0 auto",
  aspectRatio: `${cropWidth} / ${cropHeight}`
}}>
    <img src={src} alt={alt} width={width} height={height} style={{
  position: "absolute",
  display: "block",
  margin: 0,
  maxWidth: "none",
  width: `${width / cropWidth * 100}%`,
  height: "auto",
  left: `${-x / cropWidth * 100}%`,
  top: `${-y / cropHeight * 100}%`
}} />
  </div>;

## Inspect usage

In **Settings → Usage**, you can inspect gateway activity in a 30-day heatmap, daily token and request totals, and breakdowns by model.

The checkout fix can produce several model requests: one to decide what to inspect, others to work through the file contents and test results. Each call contributes to the request and token totals. A task therefore has no one-to-one relationship with a request count; use its session timeline to see which actions the agent took.

Hover over a day to inspect its activity and use **Refresh** for recent data. Cost or budget cards appear only when the service provides that information to your account. A missing card is not a zero balance or proof that the activity had no cost.

## Find where a task stopped

Start with the last unsuccessful action in the session timeline. A gateway error, a project command failure, and an approval request need different responses:

| What you see | What to check first |
| - | - |
| No response or no available models | Account access, gateway URL, and **Test connection**. |
| Tool request waiting for a decision | The pending approval or question in the session. |
| A command failed | Its full output, working folder, and installed project tools. |
| A connector returned an error | Connector authorization, **Test**, and access to the requested resource. |
| A completed answer but an unexpected result | The actual diff, test output, or browser state. |

After correcting the cause, ask the agent to repeat the specific failed check. For example: “The project dependencies are installed now. Run npm test again and report the result.” This provides a new verification result without assuming the earlier attempt succeeded.

<Frame caption="Test connection confirms access and lists available models. This example uses a local demonstration gateway.">
  <ScreenshotCrop src="/images/mka1-code/guides/troubleshooting.jpg" alt="Successful connection test with one model available" width={2720} height={1660} x={1030} y={30} cropWidth={1080} cropHeight={520} maxWidth="100%" />
</Frame>

## Troubleshooting

Check the error message in the app or tool result, then find the matching symptom below.

With the CLI installed, `mka1-code doctor` checks the coding runtime, account, gateway model catalog, connector configuration, and terminal setup. Read the individual results, including warnings, to find which part of the setup needs attention. For a connector problem, also run **Test** in **Extensions**; that checks the connection and whether the server's tools can be discovered.

<AccordionGroup>
  <Accordion title="Sign-in does not complete">
    If the browser did not open, reopen the authorization page from the app. If the code expired, choose **Request a new code** and complete authorization again. An expired account session requires signing in again. For a connection error, check the server URL and your network connection before retrying.
  </Accordion>

  <Accordion title="A project command cannot find a tool or dependency">
    Check the command output and the session's selected project folder. The build tool, test runner, and dependencies must be installed in the environment running the task. For SSH, WSL, or Docker, check that environment rather than your desktop. A new worktree may need the project's normal setup steps before it can run tests.
  </Accordion>

  <Accordion title="A connector is unavailable or its tools do not appear">
    In **Settings → Extensions**, check that the connector is enabled, complete any requested sign-in or configuration, and choose **Test**. Inspect the reported error or discovered tools. Configuration changes apply when the agent next starts a run; an active run finishes with its existing configuration.
  </Accordion>

  <Accordion title="A remote workspace will not connect">
    Confirm that the target and project folder exist. For SSH, establish a working terminal connection first and ensure authentication does not require a prompt. For Docker, check that the container is running and reachable through your Docker context. Inspect the connection dialog's error for missing remote tools or an unsupported environment.
  </Accordion>

  <Accordion title="A scheduled task did not run">
    Check that the schedule is enabled, the desktop app remained running, and the computer was awake. Inspect the run history: overlapping work on the same schedule or project can cause a skipped run, and the saved permission mode can require your attention. Missed occurrences are not retried automatically.
  </Accordion>

  <Accordion title="A commit or push failed">
    Resolve the Git error shown in the dialog. If files or staging changed during review, choose **Refresh changes** and select the files again. Resolve merge conflicts and finish ongoing Git operations before committing. If only the push failed, use **Retry push** to send the existing local commit.
  </Accordion>

  <Accordion title="The model picker is empty">
    In **Settings → Connection**, test access with the active credential and confirm the gateway URL. Save any connection edits, then refresh the model list. If authentication works but the catalog remains empty, ask your administrator which models are enabled for this account. Enter a manual model ID only when the responsible team supplies it.
  </Accordion>

  <Accordion title="A project preference is not being used">
    Open **Settings → Projects** and check the account, folder, and effective memory setting. A different worktree has its own preferences, and API-key-only access does not enable memory. If a memory change interrupted a turn, resend the request. See [Project memory](/docs/mka1-code/memory).
  </Accordion>

  <Accordion title="A document preview does not open">
    Confirm that the file exists inside the local session folder and uses a supported format. Choose **Try again** or **Refresh preview** after the file is regenerated. Remote and cloud sessions do not provide this preview. Open password-protected or unsupported Office files in their original application.
  </Accordion>
</AccordionGroup>

## Report a reproducible problem

When contacting the team responsible for your installation, include the app version from **Settings → About**, operating system, local or remote environment, and the steps that led to the failure. Copy the relevant error and describe the expected result. For a CLI problem, include the failed diagnostic check from `mka1-code doctor`.

A useful report identifies one failure precisely: “In a local Code session, selecting Test connection after sign-in returns this error; the model picker remains empty.” Remove API keys, authorization codes, personal account details, and unrelated project content from screenshots or logs before sharing.