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

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.

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.
• 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.
• 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.

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.

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.

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.

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 and the presentation logic in 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.

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	Defines the SessionStatus enum including Blocked.
packages/ui/src/session-status-presentation.ts	Translates blocked sessions into UI presentation layers.
docs/archive/design-system-v0.2-wave-10.md	UI specification defining blockedReason values and tooltip text.
docs/session-todo-lifecycle.md	Describes the full session lifecycle state transitions.
packages/eval/README.md	Documents the egress proxy HTTP 451 response mechanism.
docs/archive/maka-memory-whitebox-contract.md	Defines incognito_blocked and privacy context rules.
docs/archive/computer-use-runtime-hardening.md	Lists sensitivity_blocked and user_stopped reasons.
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 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}