# Why Is My Maka Session Blocked? Complete Guide to BlockedReason Codes and Causes

> Troubleshoot blocked Maka sessions. Understand common causes like missing config, bad credentials, and permission errors. Resolve your Maka session issues fast.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: how-to-guide
- Published: 2026-09-08

---

**A Maka session becomes blocked when the runtime encounters missing configuration, invalid credentials, permission denials, security violations, or network egress restrictions, with each block recorded in the `blockedReason` field of the session state.**

The `apache/maka` repository implements a robust session lifecycle that transitions into a **blocked** state whenever the system cannot safely continue execution. Understanding why a **Maka session is blocked** requires examining the architectural validation layers, permission models, and error handling paths defined in the source code.

## Core Architectural Reasons for Blocked Sessions

The runtime categorizes blocks into distinct failure domains. Each domain maps to a specific `blockedReason` string defined in the design system specifications and implemented in [`packages/ui/src/status-vocabulary.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/status-vocabulary.ts).

### Configuration and Credential Failures

Sessions block immediately when prerequisite settings are absent:

- **`missing_configuration`** — Required settings such as API keys or endpoint URLs are absent or malformed according to [`docs/archive/design-system-v0.2-wave-10.md`](https://github.com/apache/maka/blob/main/docs/archive/design-system-v0.2-wave-10.md).
- **`missing_credentials`** — No valid authentication token or secret exists for the requested tool or service.

### Permission and Privacy Restrictions

Privacy contexts and permission sets enforce strict boundaries:

- **`permission_denied`** (also `session_permission_blocked`) — The session attempts an operation that the active permission set forbids.
- **`incognito_blocked`** — The workspace operates in *incognito* mode, which disallows external network calls as defined in [`docs/archive/maka-memory-whitebox-contract.md`](https://github.com/apache/maka/blob/main/docs/archive/maka-memory-whitebox-contract.md).
- **`artifact_sandbox_blocked`** — Access targets an artifact that has been sandbox-deleted or is otherwise inaccessible per `docs/archive/maka-capability-audit-v1`.

### Security and Sensitivity Blocks

Security scanners and sensitivity policies trigger protective blocks:

- **`sensitivity_blocked`** — A screenshot or visual capture fails a sensitivity check (e.g., policy-level "high") according to `docs/archive/computer-use-runtime-hardening`.
- **`security_check_blocked`** — The skill scanner flags a threat level (medium or high) and the security check refuses execution as detailed in [`docs/archive/expert-team-implementation.md`](https://github.com/apache/maka/blob/main/docs/archive/expert-team-implementation.md).

### Tool and Execution Failures

Runtime tool execution errors convert directly to blocked states:

- **`tool_failure`** — The invoked tool (code executor, browser sandbox, or skill) returns a structured error.
- **`no_vision_route`** — The computer-use subsystem cannot obtain a fresh screenshot required for the action.
- **`blocked_url`** — A URL that the computer-use tool attempts to navigate is prohibited by the sandbox per `docs/computer-use-host-events-contract`.

### Network and Egress Restrictions

Network layers enforce contamination rules:

- **`egress_rule_blocked`** — An HTTP request matches a contamination rule and receives an HTTP 451 response with the `X-Maka-Eval-Egress-Rule` header, as documented in [`packages/eval/README.md`](https://github.com/apache/maka/blob/main/packages/eval/README.md).

### User and System Termination

Explicit or indeterminate termination states:

- **`user_stopped`** — The user explicitly stops the session via UI interaction.
- **`unknown`** — The runtime cannot determine a concrete cause but still marks the session as blocked.

## How the Runtime Determines a Block

The system evaluates four primary execution checkpoints before marking a session as blocked.

**Pre-flight validation** occurs before a tool is dispatched. The runtime checks configuration, credentials, and permission sets; any failure immediately sets the session to **blocked** with the corresponding reason.

**Tool execution** promises can reject with structured errors (e.g., `error('sensitivity_blocked', …)`). The runtime catches these rejections in the execution handler and converts them to a blocked session state.

**Network egress** flows through a proxy that inserts an HTTP 451 response with the `X-Maka-Eval-Egress-Rule` header when rules match; the client interprets this as `egress_rule_blocked`.

**Privacy context** enforcement occurs when the workspace privacy flag is active, pre-emptively blocking any outbound request before network contact.

All paths converge on the **`SessionStatus`** state machine implemented in [`packages/ui/src/session-status-presentation.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/session-status-presentation.ts).

## Detecting Blocked Sessions in Code

Applications can inspect session status using the UI status vocabulary. The `SessionStatus.Blocked` enum value indicates a halted session, with the specific cause available in the `blockedReason` property.

```typescript
import { getSession } from '@maka/client';
import { SessionStatus } from '@maka/ui/src/status-vocabulary';

async function logBlockReason(sessionId: string) {
  const session = await getSession(sessionId);
  if (session.status === SessionStatus.Blocked) {
    console.info(
      `Session ${sessionId} is blocked – reason: ${session.blockedReason}`
    );
  } else {
    console.info(`Session ${sessionId} status: ${session.status}`);
  }
}

```

This pattern relies on the status definitions in [`packages/ui/src/status-vocabulary.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/status-vocabulary.ts) and the presentation logic in [`session-status-presentation.ts`](https://github.com/apache/maka/blob/main/session-status-presentation.ts).

## Raising Custom Blocks from Tools

Tool developers can trigger blocks by throwing structured errors that the runtime maps to `blockedReason` values. The runtime parses the JSON error code and transitions the session to **blocked**.

```typescript
export async function runSensitiveTool(params: any) {
  if (!hasRequiredCreds()) {
    throw new Error(
      JSON.stringify({ code: 'missing_credentials', message: 'No API token' })
    );
  }
  // … normal execution …
}

```

The runtime intercepts the thrown error, extracts the `code` field, and updates the session status accordingly.

## Key Source Files for Blocked Session Logic

| File | Role |
|------|------|
| [`packages/ui/src/status-vocabulary.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/status-vocabulary.ts) | Defines the `SessionStatus` enum including `Blocked`. |
| [`packages/ui/src/session-status-presentation.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/session-status-presentation.ts) | Translates blocked sessions into UI presentation layers. |
| [`docs/archive/design-system-v0.2-wave-10.md`](https://github.com/apache/maka/blob/main/docs/archive/design-system-v0.2-wave-10.md) | UI specification defining `blockedReason` values and tooltip text. |
| [`docs/session-todo-lifecycle.md`](https://github.com/apache/maka/blob/main/docs/session-todo-lifecycle.md) | Describes the full session lifecycle state transitions. |
| [`packages/eval/README.md`](https://github.com/apache/maka/blob/main/packages/eval/README.md) | Documents the egress proxy HTTP 451 response mechanism. |
| [`docs/archive/maka-memory-whitebox-contract.md`](https://github.com/apache/maka/blob/main/docs/archive/maka-memory-whitebox-contract.md) | Defines `incognito_blocked` and privacy context rules. |
| [`docs/archive/computer-use-runtime-hardening.md`](https://github.com/apache/maka/blob/main/docs/archive/computer-use-runtime-hardening.md) | Lists `sensitivity_blocked` and `user_stopped` reasons. |
| [`docs/archive/expert-team-implementation.md`](https://github.com/apache/maka/blob/main/docs/archive/expert-team-implementation.md) | Details the security scanner and `security_check_blocked` logic. |

## Summary

- A **Maka session is blocked** by the runtime whenever continued execution would violate security, privacy, or configuration constraints.
- The `blockedReason` field provides granular diagnostics including `missing_configuration`, `permission_denied`, `egress_rule_blocked`, and `sensitivity_blocked`.
- Blocks originate from pre-flight validation, tool execution errors, network egress proxies (HTTP 451), or privacy context enforcement.
- Developers can detect blocked states by checking `SessionStatus.Blocked` in [`packages/ui/src/status-vocabulary.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/status-vocabulary.ts) and inspect the `blockedReason` property for specific causes.

## Frequently Asked Questions

### What does the `blockedReason` field contain?

The `blockedReason` field contains a string identifier that specifies why a session entered the blocked state. Valid values include `missing_credentials`, `tool_failure`, `incognito_blocked`, `security_check_blocked`, and `egress_rule_blocked`, among others defined in the design system documentation.

### How can I programmatically check if a Maka session is blocked?

Import `SessionStatus` from `@maka/ui/src/status-vocabulary` and compare `session.status` to `SessionStatus.Blocked`. If true, read `session.blockedReason` to determine the specific cause and display appropriate user messaging.

### What triggers an `egress_rule_blocked` status?

This status occurs when the session attempts an HTTP request that matches a contamination rule in the egress proxy. The proxy returns HTTP 451 with the `X-Maka-Eval-Egress-Rule` header, which the Maka client interprets as `egress_rule_blocked` per [`packages/eval/README.md`](https://github.com/apache/maka/blob/main/packages/eval/README.md).

### Can user actions cause a session to block?

Yes. When a user explicitly clicks "Stop" or terminates the session via the UI, the runtime sets the status to blocked with the reason `user_stopped`. This is distinct from system-initiated blocks like `unknown` or `tool_failure`.