Troubleshooting | airlock docs

A growing set of recipes for common airlock failure modes. If you hit something we haven't documented yet, the audit log and the Security → Security logs feed are the two surfaces with the most diagnostic detail.

My agent says an AI Use Policy signature is required

If every tool call comes back with "AI Use Policy acknowledgement required", your organization has published an AI use policy and switched enforcement on. No tool call was made: nothing was executed, and nothing was denied on its merits.

Open the link in the message (the /policy page in the Control Room), read the policy, and sign it. Then wait a few seconds before retrying, because a fresh signature is honoured within about 15 seconds, so an immediate retry may still be refused once. Publishing a new version that requires re-acknowledgement puts you back in the same state.

Approvers: approving a queued request can return a conflict and leave it PENDING when the person who raised it has not signed. That is deliberate: the request is held, not rejected. Once they sign, approve the same request again and it runs.

Admins: enforcement is staged on Rules → Enforcement. Service accounts and service tokens are always exempt; being an admin is not an exemption.

Why is my MCP token getting 403?

A bearer credential that worked yesterday and returns 403 forbidden today is almost always one of these.

"My token suddenly stopped working"

Open Security → Security logs and filter by the Access chip (admin access required, so ask an admin if you are a member). An allowlist denial reads "<actor> was blocked by the IP allowlist from <source IP>", and its Detection field names the layer that rejected it: allowlist miss at the org layer (a rule covering every token in the org) or at the entity layer (a per-service-account or per-token override).

If no allowlist denial matches, the 403 is coming from somewhere else in the auth chain:

Your user account is not ACTIVE yet: still invited, or awaiting admin approval.
You were removed from the organization.
The service account behind the token was disabled or deleted.
For browser-based clients only: the request's Origin is not on airlock's allowlist.
The AI client you are connecting through was disabled under Rules → Allowed AI clients, or you are outside its space scope.

Note that a policy DENY, an exceeded token budget, and a security block do not produce a 403. Those come back as a successful HTTP response carrying an error tool result, so the agent shows an error message while the credential itself is fine. To investigate those, open History, pick the integration involved, and look for an API_EXECUTED row with outcome: failure. The audit view is per-integration, so you must select one first, and an IP-allowlist denial carries no integration, which is why it never appears there.

"I added my IP and saved, but my agent still gets 403"

The agent's egress IP almost certainly differs from the IP your browser was on when you added the entry. If the agent runs from a VPC NAT gateway, a cloud VM, or a CI job, that's usually a different address.

Two ways to check:

Submit a deliberately-failing call from the agent and read its source IP off the denial in Security → Security logs.
From the agent host, query an "echo" service (e.g. curl https://api.ipify.org) to see its egress IP, then add that CIDR to the allowlist.

"My NAT IP rotated and now nothing works"

This is the expected failure mode for cloud egress that uses a pool of NAT addresses. Recovery:

Open Security → Security logs and filter by Access.
Read the source IP off the denial.
Add the new CIDR to the relevant allowlist and save. The org allowlist is on Rules → Network access; a per-service-account allowlist is on that service account's detail page.

If the NAT pool churns frequently, prefer the broader containing CIDR. A /16 covers 65,536 addresses; that's usually large enough to cover an entire cloud-provider NAT range without daily edits.

The org-level allowlist applies to every MCP caller: service tokens, personal tokens, and interactive OAuth sessions alike. What is not yet available is a per-user allowlist: you can scope CIDRs per service account or per service token, but not per person.

So for genuinely dynamic egress (developer laptops on residential ISPs) you have two options: leave the org allowlist empty and rely on the policy / approval / security-block layers, or list a CIDR broad enough to cover everyone who connects. An org allowlist that only covers your office blocks every remote member's agent.

When an AI client fails to connect, the sign-in screen says why. The three messages that need someone to act:

"This application's callback (…) is not approved for your organization"

airlock does not recognize this client yet. The message names the client's callback address, and the screen has a Copy redirect URL button next to it. Send that address to an admin, who adds it as a custom client under Rules → Allowed AI clients. Then try connecting again.

"This connection's registration is no longer recognized"

The client is presenting a registration airlock no longer has, so the allowlist is not the problem. Remove the airlock connection in your AI client, add it back, and sign in again. Re-adding it makes the client register afresh.

"This AI client has been disabled for your organization"

An admin switched the client off under Rules → Allowed AI clients. Only an admin can turn it back on. Turning a client off also ends sessions that were already connected, within 8 hours.

If the sign-in screen shows the wrong account under Signed in as, click Use a different account before authorizing.

My integration says "Credentials rejected"

"Credentials rejected by <integration> on <date>" under Your connection on the integration's Settings tab means the provider started refusing a key that used to work, usually because it was revoked, rotated or expired at the provider. Create a new key with the provider and save it on the same tab.

When you save a key, airlock tries it with the provider first. A refused key is not saved at all, and the message shows the provider's reason. Admins see how many members' keys were rejected under Your connection on the integration's Settings tab.

SharePoint Excel tools fail after connecting

The Excel tools need one more Microsoft permission than SharePoint used to ask for. A SharePoint connection made before Excel support keeps its old permissions, so its Excel calls are refused. Open the integration's Settings tab: under Your connection it says This connection is missing a permission. Click Reconnect Account and sign in again. Other connections that are missing a newly required permission show the same notice and are fixed the same way.

Interactive views do not show in my AI client

Some integrations show an interactive view in the conversation, such as a Metabase chart. airlock shows it inside its own frame, labelled as a third-party widget, through one tool called airlock_widget. When the view does not appear, the message you see points to the cause.

The agent answers in text and no view appears

Interactive UI is off for the integration. An admin turns it on in the Control Room: open the integration, then Settings, and switch on Allow interactive UI from this integration. It is off by default.
Claude has not allowed airlock_widget. Claude lists a new tool as blocked until someone allows it, without saying so in the chat. Allow airlock_widget once under Settings → Connectors → airlock. After that, Claude no longer asks to allow it for any integration's view, until an airlock update changes the tool: Claude then asks once more. airlock's own policies, including approvals, still apply to every call.
The client does not support interactive views. Only clients that support MCP Apps show them. Every other client gets the same result as text.
You are in Claude Code. Claude Code lists airlock_widget too, because it shares the airlock connector with Claude Desktop, but it cannot show a view. airlock answers it with text, and a chart-only tool tells the agent to fetch the data instead.

"The airlock tools in this conversation do not include airlock_widget"

Claude keeps one copy of the airlock connector's tools, shared by Claude Desktop, claude.ai and Claude Code. A copy saved by an earlier version of airlock can lack the interactive tools, for example when Claude Code started with your claude.ai connectors after you connected airlock in Claude Desktop. airlock now gives every Claude app the same tools, so this only affects an old copy.

To restore the interactive tools:

In Claude Desktop or claude.ai, open Settings → Connectors, choose airlock, and select Refresh tools list from its menu.
Allow airlock_widget and the other airlock tools you use again. Claude lists refreshed tools as blocked.
Start a new chat and ask again.

"Could not connect to Metabase"

The view loaded, but your Metabase refused to talk to it. A Metabase admin turns on your AI client under the MCP Apps CORS setting in Metabase's AI settings (for example Claude or ChatGPT). Each client needs its own switch.

If ChatGPT still shows this message after its switch is on, add codex-sandbox://*.web-sandbox.oaiusercontent.com as a custom origin in the same settings. Some ChatGPT apps load views from that address, and the ChatGPT switch does not cover it.

airlock could not fetch the integration's view. The result is still available to the agent as text. Check that the integration is still connected (sign in to it again from the Control Room if its connection expired), then ask again.

ChatGPT still shows an old error after an update

ChatGPT keeps its own copy of a connector's tools and views. Open ChatGPT's settings, find the airlock connector under Apps & Connectors, choose Refresh, and start a new chat.

Resetting an admin lockout

You cannot lock yourself out of the Control Room UI with the MCP IP allowlist, because Cognito governs that sign-in, not the MCP token allowlist. If the lockout modal showed up because you genuinely intended to lock the connection (e.g. jump-host admins managing the policy from outside the allowed range), sign in again from the Control Room and edit the list back.

If you somehow lost Cognito access too, contact airlock support; there's no MCP-side mitigation for a Cognito-side lockout.