n8n-io/n8n · error · Error

Failed to upload capabilities: ${response.status} ${text}

Error message

Failed to upload capabilities: ${response.status} ${text}

What it means

Thrown by uploadCapabilities() when the gateway init endpoint returns a non-OK status that is NOT 401/403 (those throw GatewayAuthError separately). Covers 4xx client errors and 5xx server errors from the /rest/instance-ai/gateway/init endpoint during tool capability registration.

Source

Thrown at packages/@n8n/computer-use/src/gateway-client.ts:318

		headers.set('Content-Type', 'application/json');
		headers.set('X-Gateway-Key', this.apiKey);
		const response = await fetch(url, {
			method: 'POST',
			headers,
			body: JSON.stringify({
				rootPath: this.dir,
				tools,
				hostIdentifier: `${os.userInfo().username}@${os.hostname()}`,
				toolCategories: this.activeToolCategories,
			}),
		});

		if (!response.ok) {
			const text = await response.text();
			if (response.status === 401 || response.status === 403) {
				throw new GatewayAuthError(response.status, text);
			}
			throw new Error(`Failed to upload capabilities: ${response.status} ${text}`);
		}

		// If the server returned a session key, switch to it for all subsequent requests
		// n8n wraps controller responses in { data: ... }
		const body = (await response.json()) as { data: { ok: boolean; sessionKey?: string } };
		if (body.data.sessionKey) {
			this.sessionKey = body.data.sessionKey;
			logger.debug('Pairing token consumed, switched to session key');
		}

		logger.debug('Capabilities uploaded', { toolCount: tools.length });
	}

	private connectSSE(): void {
		const url = `${this.options.url}/rest/instance-ai/gateway/events`;

		logger.debug('Connecting to gateway', { keyPrefix: this.apiKey.slice(0, 8) });
		const apiKey = this.apiKey;

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Check the response status and text in the error message for the specific failure
2. For 5xx: retry with backoff or check n8n server health and logs
3. For 4xx: verify tool definitions produce valid JSON schemas
4. Ensure the computer-use package version is compatible with the n8n server version

function isUploadCapabilitiesError(e: unknown): boolean {
  return e instanceof Error && e.message.startsWith('Failed to upload capabilities:');
}

const MAX_RETRIES = 3;
for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
  try {
    await gatewayClient.start();
    break;
  } catch (e) {
    const status = e instanceof Error ? parseInt(e.message.match(/\d{3}/)?.[0] ?? '0') : 0;
    if (status >= 500 && attempt < MAX_RETRIES - 1) {
      await new Promise(r => setTimeout(r, 2000 * (attempt + 1)));
      continue;
    }
    throw e;
  }
}

When it happens

Trigger: Gateway returns 400 (malformed tool payload or schema serialization failure), 409 (session already initialized), 500 (n8n internal error), 502/503 (gateway unavailable or overloaded).

Common situations: Tool definition with an inputSchema that fails zodToJsonSchema serialization, n8n server bug, gateway under heavy load, version mismatch between computer-use client and server API.

Related errors

• Gateway rejected token: ${status} ${body}
• Credential creation failed: ${res.status} ${text}
• Failed to list ${provider} models (status ${response.status}
• Webhook request failed: ${response.status} ${response.status
• Request failed with status code ${response.status}

AI-assisted analysis of n8n-io/n8n@5ac6606e81 (2026-08-12). Data as JSON: /api/errors/de0b002fd70d76fe. Report an issue: GitHub.