Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🪵 fix: Explain Failed Attachment Copies and Subagent Start-Up Failures (#17398)

Danny Avila3ccdd252f937
diff --git a/packages/api/src/agents/__tests__/run-codeTools.test.ts b/packages/api/src/agents/__tests__/run-codeTools.test.ts
index e6da4f20cd..fe2bc395e1 100644
--- a/packages/api/src/agents/__tests__/run-codeTools.test.ts
+++ b/packages/api/src/agents/__tests__/run-codeTools.test.ts
@@ -5,6 +5,7 @@ import type { TFile } from 'librechat-data-provider';
import type { ProvisionCallbackDeps, ProvisionToolContext } from '~/files/provision/callback';
import type { HostSubagentTaskConfig } from '~/agents/subagentDelivery';
import type { ServerRequest } from '~/types';
+import { reportSubagentResolutionFailure } from '~/agents/failures/subagent';
import { createProvisionFilesCallback } from '~/files/provision/callback';
import { SUBAGENT_COMPLETION_DELIVERY } from '~/agents/subagentDelivery';
import { mergeCodeFilesIntoContext } from '~/agents/codeFilesSession';
@@ -528,6 +529,11 @@ describe('createRun code-tool eager/session wiring', () => {
);
});
+ it('reports why a subagent could not start instead of leaving the SDK to guess', async () => {
+ const runConfig = await captureRunConfig();
+ expect(runConfig.onSubagentResolutionFailure).toBe(reportSubagentResolutionFailure);
+ });
+
it('passes the trusted per-agent code-session partition to the SDK', async () => {
const codeSessionKey = 'execute_code:stateful:v1:user';
const runConfig = await captureRunConfig(makeAgent({ codeSessionKey }));
diff --git a/packages/api/src/agents/failures/subagent.spec.ts b/packages/api/src/agents/failures/subagent.spec.ts
new file mode 100644
index 0000000000..e464cea742
--- /dev/null
+++ b/packages/api/src/agents/failures/subagent.spec.ts
@@ -0,0 +1,202 @@
+import { logger } from '@librechat/data-schemas';
+import { SubagentResolutionError } from '@librechat/agents';
+import type { SubagentResolutionDiagnostic } from '@librechat/agents';
+import {
+ describeErrorCauses,
+ describeStackFrames,
+ findMCPAuthenticationFailure,
+ reportSubagentResolutionFailure,
+} from './subagent';
+import { MCPAuthenticationRefreshError, MCPAuthenticationRejectedError } from '~/mcp/errors';
+import { ReauthenticationRequiredError } from '~/mcp/oauth/tokens';
+import { OpenIDReauthRequiredError } from '~/utils/oidc';
+
+const SECRET = 'provider-secret-value';
+
+function diagnostic(
+ overrides: Partial<SubagentResolutionDiagnostic> = {},
+): SubagentResolutionDiagnostic {
+ return {
+ phase: 'config',
+ subagentType: 'pr-reviewer',
+ aborted: false,
+ type: 'Error',
+ cause: 'unknown',
+ message: 'Subagent error: Unable to initialize the selected subagent.',
+ parentRunId: 'run-1',
+ childRunId: 'child-run-1',
+ taskId: 'task-1',
+ ...overrides,
+ };
+}
+
+describe('describeErrorCauses', () => {
+ it('keeps name, code and status of every cause, but a message only from trusted errors', () => {
+ const root = Object.assign(new Error(`Token refresh failed: api_key=${SECRET}`), {
+ code: 'invalid_grant',
+ status: 400,
+ });
+ const error = new SubagentResolutionError('config', 'unknown');
+ Object.assign(error, { cause: root });
+
+ const causes = describeErrorCauses(error);
+
+ expect(causes).toEqual([
+ {
+ name: 'SubagentResolutionError',
+ message: 'Subagent error: Unable to initialize the selected subagent.',
+ },
+ { name: 'Error', code: 'invalid_grant', status: 400 },
+ ]);
+ expect(JSON.stringify(causes)).not.toContain(SECRET);
+ });
+
+ it('stops at a cycle and at its depth bound', () => {
+ const first = new Error('first');
+ const second = new Error('second', { cause: first });
+ Object.assign(first, { cause: second });
+ expect(describeErrorCauses(first)).toHaveLength(2);
+
+ let deep: unknown = new Error('0');
+ for (let index = 1; index < 10; index++) {
+ deep = new Error(String(index), { cause: deep });
+ }
+ expect(describeErrorCauses(deep)).toHaveLength(4);
+ });
+
+ it('describes values that are not errors without echoing them', () => {
+ expect(describeErrorCauses(`plain failure ${SECRET}`)).toEqual([{ name: 'string' }]);
+ expect(describeErrorCauses(undefined)).toEqual([]);
+ expect(describeErrorCauses({ name: 'bad name with spaces', code: { nested: SECRET } })).toEqual(
+ [{ name: 'UnknownError' }],
+ );
+ });
+});
+
+describe('describeStackFrames', () => {
+ it('keeps where the error was thrown and drops its message', () => {
+ const frames = describeStackFrames(new Error(`Authorization: Bearer ${SECRET}\nsecond line`));
+ expect(frames.length).toBeGreaterThan(0);
+ expect(frames.every((frame) => frame.startsWith('at '))).toBe(true);
+ expect(JSON.stringify(frames)).not.toContain(SECRET);
+ expect(describeStackFrames('not an error')).toEqual([]);
+ });
+
+ it('never mistakes a message line shaped like a frame for one', () => {
+ const injected = new Error(`provider said:${String.fromCharCode(10)} at api_key=${SECRET}`);
+ const frames = describeStackFrames(injected);
+ expect(frames.length).toBeGreaterThan(0);
+ expect(JSON.stringify(frames)).not.toContain(SECRET);
+
+ const rewritten = new Error('original');
+ void rewritten.stack;
+ rewritten.message = `rewritten ${SECRET}`;
+ expect(describeStackFrames(rewritten)).toEqual([]);
+ });
+});
+
+describe('findMCPAuthenticationFailure', () => {
+ it('names the MCP server that needs re-authentication anywhere in the cause chain', () => {
+ expect(
+ findMCPAuthenticationFailure(
+ new Error('child init failed', {
+ cause: new ReauthenticationRequiredError('clickhouse-docs', 'expired'),
+ }),
+ ),
+ ).toEqual({ serverName: 'clickhouse-docs', retryable: false });
+ expect(
+ findMCPAuthenticationFailure(new MCPAuthenticationRejectedError('github', false)),
+ ).toEqual({ serverName: 'github', retryable: false });
+ });
+
+ it('marks failures that a retry may clear as retryable', () => {
+ expect(findMCPAuthenticationFailure(new MCPAuthenticationRefreshError())).toEqual({
+ retryable: true,
+ });
+ expect(
+ findMCPAuthenticationFailure(new MCPAuthenticationRejectedError('github', true)),
+ ).toEqual({ serverName: 'github', retryable: true });
+ });
+
+ it('does not treat a model provider or other HTTP 401 as an MCP sign-in', () => {
+ expect(
+ findMCPAuthenticationFailure(Object.assign(new Error('401 invalid_grant'), { status: 401 })),
+ ).toBeUndefined();
+ expect(findMCPAuthenticationFailure(new Error('Model not found'))).toBeUndefined();
+ expect(
+ findMCPAuthenticationFailure(new OpenIDReauthRequiredError('OpenID ID token is expired')),
+ ).toBeUndefined();
+ });
+});
+
+describe('reportSubagentResolutionFailure', () => {
+ it('logs the underlying cause and the MCP server, and keeps the SDK classification', () => {
+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
+ const error = new Error(`Initialization failed: ${SECRET}`, {
+ cause: new ReauthenticationRequiredError('clickhouse-docs', 'expired'),
+ });
+
+ const cause = reportSubagentResolutionFailure(diagnostic(), error);
+
+ expect(cause).toBeUndefined();
+ expect(warn).toHaveBeenCalledWith(
+ '[subagents] Subagent could not start: an MCP server it uses needs re-authentication',
+ {
+ phase: 'config',
+ subagentType: 'pr-reviewer',
+ cause: 'unknown',
+ errorType: 'Error',
+ aborted: false,
+ taskId: 'task-1',
+ childRunId: 'child-run-1',
+ parentRunId: 'run-1',
+ mcpAuthentication: { serverName: 'clickhouse-docs', retryable: false },
+ causes: [
+ { name: 'Error' },
+ {
+ name: 'ReauthenticationRequiredError',
+ message:
+ 'Re-authentication required for "clickhouse-docs": access token expired and no refresh token available',
+ },
+ ],
+ frames: expect.arrayContaining([expect.stringMatching(/^at /)]),
+ },
+ );
+ expect(JSON.stringify(warn.mock.calls)).not.toContain(SECRET);
+ warn.mockRestore();
+ });
+
+ it('says a retry may succeed when the MCP sign-in failure is transient', () => {
+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
+
+ reportSubagentResolutionFailure(diagnostic(), new MCPAuthenticationRefreshError());
+
+ expect(warn).toHaveBeenCalledWith(
+ '[subagents] Subagent could not start: an MCP server it uses could not authenticate; a retry may succeed',
+ expect.objectContaining({ mcpAuthentication: { retryable: true } }),
+ );
+ warn.mockRestore();
+ });
+
+ it('logs other failures without an MCP reason', () => {
+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
+
+ reportSubagentResolutionFailure(
+ diagnostic({ phase: 'identity', taskId: undefined }),
+ new Error('Agent not found'),
+ );
+
+ expect(warn).toHaveBeenCalledWith('[subagents] Subagent could not start', {
+ phase: 'identity',
+ subagentType: 'pr-reviewer',
+ cause: 'unknown',
+ errorType: 'Error',
+ aborted: false,
+ childRunId: 'child-run-1',
+ parentRunId: 'run-1',
+ causes: [{ name: 'Error' }],
+ frames: expect.any(Array),
+ });
+ warn.mockRestore();
+ });
+});
diff --git a/packages/api/src/agents/failures/subagent.ts b/packages/api/src/agents/failures/subagent.ts
new file mode 100644
index 0000000000..70032fb222
--- /dev/null
+++ b/packages/api/src/agents/failures/subagent.ts
@@ -0,0 +1,210 @@
+import { logger } from '@librechat/data-schemas';
+import { SubagentResolutionError } from '@librechat/agents';
+import type { SubagentResolutionFailureHandler } from '@librechat/agents';
+import {
+ MCPAuthenticationRefreshError,
+ MCPAuthenticationRejectedError,
+ MCPTransportAuthenticationError,
+} from '~/mcp/errors';
+import { ReauthenticationRequiredError } from '~/mcp/oauth/tokens';
+import { CodeWorkspaceSelectionError } from '~/code/errors';
+import { OboTokenResolutionError } from '~/mcp/oauth/obo';
+import { OpenIDReauthRequiredError } from '~/utils/oidc';
+import { getSafeErrorText } from '~/utils/errors';
+
+/** Links of an error's `cause` chain described; deeper causes are rarely informative. */
+const MAX_CAUSE_DEPTH = 4;
+const MAX_CAUSE_MESSAGE_LENGTH = 300;
+const MAX_STACK_FRAMES = 8;
+const STACK_FRAME = /^\s+at\s/;
+const SAFE_LABEL = /^[A-Za-z0-9_.:-]{1,64}$/;
+const SAFE_SERVER_NAME = /^[\w .:@-]{1,128}$/;
+const REAUTHENTICATION_SERVER = /^Re-authentication required for "([^"]{1,128})"/;
+
+/**
+ * One link of an error chain, safe to log. A message is kept only for errors whose text
+ * LibreChat or the agents SDK writes itself; any other message may echo a credential or
+ * submitted content, so those links log their name, code and status alone.
+ */
+export interface SafeErrorCause {
+ name: string;
+ code?: string | number;
+ status?: number;
+ message?: string;
+}
+
+/** An MCP server whose sign-in failed; `retryable` when retrying may succeed without a new one. */
+export interface MCPAuthenticationFailure {
+ serverName?: string;
+ retryable: boolean;
+}
+
+function readProperty(value: object, property: string): unknown {
+ try {
+ return (value as Record<string, unknown>)[property];
+ } catch {
+ return undefined;
+ }
+}
+
+function safeLabel(value: unknown): string | undefined {
+ return typeof value === 'string' && SAFE_LABEL.test(value) ? value : undefined;
+}
+
+function safeStatus(value: unknown): number | undefined {
+ return typeof value === 'number' && Number.isInteger(value) && value >= 100 && value <= 599
+ ? value
+ : undefined;
+}
+
+function isMCPAuthenticationError(error: unknown): error is Error {
+ return (
+ error instanceof ReauthenticationRequiredError ||
+ error instanceof MCPAuthenticationRejectedError ||
+ error instanceof MCPAuthenticationRefreshError ||
+ error instanceof MCPTransportAuthenticationError ||
+ error instanceof OboTokenResolutionError
+ );
+}
+
+/** Errors whose message LibreChat or the agents SDK composes from fixed text and safe names. */
+function hasTrustedMessage(error: object): boolean {
+ return (
+ isMCPAuthenticationError(error) ||
+ error instanceof OpenIDReauthRequiredError ||
+ error instanceof SubagentResolutionError ||
+ error instanceof CodeWorkspaceSelectionError
+ );
+}
+
+function describeCause(error: unknown): SafeErrorCause {
+ if (error == null || typeof error !== 'object') {
+ return { name: typeof error };
+ }
+ const code = readProperty(error, 'code');
+ const status = safeStatus(readProperty(error, 'status') ?? readProperty(error, 'statusCode'));
+ const message = readProperty(error, 'message');
+ return {
+ name: safeLabel(readProperty(error, 'name')) ?? 'UnknownError',
+ ...(safeLabel(code) != null || (typeof code === 'number' && Number.isInteger(code))
+ ? { code: code as string | number }
+ : {}),
+ ...(status != null ? { status } : {}),
+ ...(typeof message === 'string' && message.length > 0 && hasTrustedMessage(error)
+ ? { message: getSafeErrorText(message).slice(0, MAX_CAUSE_MESSAGE_LENGTH) }
+ : {}),
+ };
+}
+
+/** Walks `error` and its `cause` chain, bounded and cycle-safe. */
+function errorChain(error: unknown): unknown[] {
+ const chain: unknown[] = [];
+ let current = error;
+ while (current != null && chain.length < MAX_CAUSE_DEPTH && !chain.includes(current)) {
+ chain.push(current);
+ current = typeof current === 'object' ? readProperty(current, 'cause') : undefined;
+ }
+ return chain;
+}
+
+/** The error and its causes by name, code, status and, for trusted errors, message. */
+export function describeErrorCauses(error: unknown): SafeErrorCause[] {
+ return errorChain(error).map(describeCause);
+}
+
+/**
+ * Where an error was thrown: the frames V8 appends after the `name: message` header. A stack
+ * whose header no longer matches its name and message is skipped, because a message line that
+ * looks like a frame could then pass for one.
+ */
+export function describeStackFrames(error: unknown): string[] {
+ if (!(error instanceof Error) || typeof error.stack !== 'string') {
+ return [];
+ }
+ const header = error.message === '' ? error.name : `${error.name}: ${error.message}`;
+ if (!error.stack.startsWith(`${header}\n`)) {
+ return [];
+ }
+ return error.stack
+ .slice(header.length + 1)
+ .split('\n')
+ .filter((line) => STACK_FRAME.test(line))
+ .slice(0, MAX_STACK_FRAMES)
+ .map((line) => getSafeErrorText(line.trim()));
+}
+
+function getServerName(error: object): string | undefined {
+ const serverName = readProperty(error, 'serverName');
+ if (typeof serverName === 'string' && SAFE_SERVER_NAME.test(serverName)) {
+ return serverName;
+ }
+ const message = readProperty(error, 'message');
+ const match = typeof message === 'string' ? REAUTHENTICATION_SERVER.exec(message) : null;
+ return match != null && SAFE_SERVER_NAME.test(match[1]) ? match[1] : undefined;
+}
+
+/** A refresh outage, or a rejection after the connection already refreshed, may pass on retry. */
+function isRetryableAuthenticationError(error: Error): boolean {
+ if (error instanceof MCPAuthenticationRefreshError) {
+ return true;
+ }
+ return (
+ (error instanceof MCPAuthenticationRejectedError || error instanceof OboTokenResolutionError) &&
+ error.retryable
+ );
+}
+
+/**
+ * The MCP server whose sign-in failed anywhere in `error`'s cause chain, or undefined when the
+ * failure is not an MCP authentication failure. Generic HTTP 401/403 errors do not count: a
+ * model provider rejecting its key is not an MCP server asking the user to sign in again.
+ */
+export function findMCPAuthenticationFailure(error: unknown): MCPAuthenticationFailure | undefined {
+ for (const link of errorChain(error)) {
+ if (isMCPAuthenticationError(link)) {
+ const serverName = getServerName(link);
+ return {
+ ...(serverName == null ? {} : { serverName }),
+ retryable: isRetryableAuthenticationError(link),
+ };
+ }
+ }
+ return undefined;
+}
+
+/**
+ * Logs why a subagent could not start, which the SDK otherwise reports only as a fixed
+ * `cause`. Leaves the SDK's classification unchanged: its causes cannot yet say that an MCP
+ * server needs re-authentication, so that reason is logged rather than shown.
+ */
+export const reportSubagentResolutionFailure: SubagentResolutionFailureHandler = (
+ detail,
+ error,
+) => {
+ const mcpAuthentication = findMCPAuthenticationFailure(error);
+ logger.warn(
+ `[subagents] Subagent could not start${describeMCPAuthenticationFailure(mcpAuthentication)}`,
+ {
+ phase: detail.phase,
+ subagentType: detail.subagentType,
+ cause: detail.cause,
+ errorType: detail.type,
+ aborted: detail.aborted,
+ ...(detail.taskId != null ? { taskId: detail.taskId } : {}),
+ ...(detail.childRunId != null ? { childRunId: detail.childRunId } : {}),
+ ...(detail.parentRunId != null ? { parentRunId: detail.parentRunId } : {}),
+ ...(mcpAuthentication != null ? { mcpAuthentication } : {}),
+ causes: describeErrorCauses(error),
+ frames: describeStackFrames(error),
+ },
+ );
+};
+
+function describeMCPAuthenticationFailure(failure: MCPAuthenticationFailure | undefined): string {
+ if (failure == null) {
+ return '';
+ }
+ return failure.retryable
+ ? ': an MCP server it uses could not authenticate; a retry may succeed'
+ : ': an MCP server it uses needs re-authentication';
+}
diff --git a/packages/api/src/agents/run.ts b/packages/api/src/agents/run.ts
index 0232a992ff..c0ea3aebfb 100644
--- a/packages/api/src/agents/run.ts
+++ b/packages/api/src/agents/run.ts
@@ -119,6 +119,7 @@ import { resolveConfigHeaders, resolveModelHeaders, mergeHeaders } from '~/utils
import { interruptToolHandler, supportsRunInterruption } from '~/agents/steering/tools';
import { extractDefaultParams, resolveReasoningParams } from '~/endpoints/openai/llm';
import { getLLMConfig as getAnthropicLLMConfig } from '~/endpoints/anthropic/llm';
+import { reportSubagentResolutionFailure } from '~/agents/failures/subagent';
import { createScheduledMCPRunPolicy } from '~/schedules/authorization/run';
import { CREATE_FILE_TOOL_NAME, EDIT_FILE_TOOL_NAME } from '~/agents/tools';
import { buildAgentInitialToolSessions } from '~/agents/codeFilesSession';
@@ -3055,6 +3056,8 @@ export async function createRun({
indexTokenCountMap,
subagentUsageSink,
subagentTasks: activeSubagentTasks,
+ // Without it a subagent that cannot start logs nothing beyond the SDK's fixed `cause`.
+ onSubagentResolutionFailure: reportSubagentResolutionFailure,
...(runFilesActive &&
runFiles != null && {
subagentContext: { prepare: runFiles.prepare, complete: runFiles.complete },
diff --git a/packages/api/src/agents/subagentThreads.spec.ts b/packages/api/src/agents/subagentThreads.spec.ts
index e253b18f99..9c2eebbc0c 100644
--- a/packages/api/src/agents/subagentThreads.spec.ts
+++ b/packages/api/src/agents/subagentThreads.spec.ts
@@ -1,6 +1,7 @@
import mongoose from 'mongoose';
import { randomUUID } from 'node:crypto';
import { MongoMemoryServer } from 'mongodb-memory-server';
+import { SubagentResolutionError } from '@librechat/agents';
import { Constants, EModelEndpoint } from 'librechat-data-provider';
import { AIMessage, HumanMessage, ToolMessage } from '@librechat/agents/langchain/messages';
import {
@@ -2525,8 +2526,9 @@ describe('SubagentThreadTaskStore', () => {
}
});
- it('does not persist arbitrary executor details into the visible child chat', async () => {
- loggerErrorSpy.mockClear();
+ it('does not persist or log arbitrary executor details', async () => {
+ /** `restoreMocks` removes the suite-wide spy after the first test. */
+ const errorSpy = jest.spyOn(logger, 'error').mockImplementation(() => logger);
const userId = 'safe-error-user';
const parentConversationId = randomUUID();
await saveParent(userId, parentConversationId);
@@ -2552,7 +2554,50 @@ describe('SubagentThreadTaskStore', () => {
expect(
JSON.stringify(store.claim(config.scopeId, requireAccepted(started).task.taskId)),
).not.toContain('provider-secret');
- expect(JSON.stringify(loggerErrorSpy.mock.calls)).not.toContain('provider-secret');
+ expect(errorSpy).toHaveBeenCalledWith(
+ '[subagentThreads] Child-thread execution failed',
+ expect.objectContaining({
+ causes: [{ name: 'Error' }],
+ frames: expect.arrayContaining([expect.stringMatching(/^at /)]),
+ }),
+ );
+ expect(JSON.stringify(errorSpy.mock.calls)).not.toContain('provider-secret');
+ });
+
+ it('shows why a subagent could not start and logs the failure for its task', async () => {
+ const errorSpy = jest.spyOn(logger, 'error').mockImplementation(() => logger);
+ const userId = 'resolution-error-user';
+ const parentConversationId = randomUUID();
+ await saveParent(userId, parentConversationId);
+ const store = new SubagentThreadTaskStore(methods);
+ const config = buildSubagentThreadTaskConfig(store, { userId, parentConversationId });
+ const started = store.start(
+ taskRequest(config.scopeId, {
+ run: async () => {
+ throw new SubagentResolutionError('config', 'workspace_unavailable');
+ },
+ }),
+ );
+ await waitForSettled(store, config.scopeId, started);
+
+ const message =
+ 'Subagent error: Workspace unavailable. Retry later or choose another workspace.';
+ const messages = await methods.getMessages({
+ user: userId,
+ conversationId: requireThreadId(started),
+ });
+ expect(messages[messages.length - 1]?.text).toBe(`Subagent task failed: ${message}`);
+ expect(errorSpy).toHaveBeenCalledWith(
+ '[subagentThreads] Child-thread execution failed',
+ expect.objectContaining({
+ taskId: requireAccepted(started).task.taskId,
+ detail: message,
+ errorName: 'SubagentResolutionError',
+ phase: 'config',
+ resolutionCause: 'workspace_unavailable',
+ causes: [{ name: 'SubagentResolutionError', message }],
+ }),
+ );
});
it('routes live task polling and controls to the replica that owns the execution', async () => {
diff --git a/packages/api/src/agents/subagentThreads.ts b/packages/api/src/agents/subagentThreads.ts
index c7ea66fbc8..4bca8fefb2 100644
--- a/packages/api/src/agents/subagentThreads.ts
+++ b/packages/api/src/agents/subagentThreads.ts
@@ -1,6 +1,6 @@
import { randomUUID } from 'node:crypto';
-import { InMemorySubagentTaskStore } from '@librechat/agents';
import { logger, tenantStorage } from '@librechat/data-schemas';
+import { InMemorySubagentTaskStore, SubagentResolutionError } from '@librechat/agents';
import { EModelEndpoint, Constants, subagentActivityConfigSchema } from 'librechat-data-provider';
import {
mapChatMessagesToStoredMessages,
@@ -55,6 +55,7 @@ import {
} from './activity';
import { boundSubagentActivityUpdate, SubagentActivityStream } from './subagentActivity';
import { createSubagentAttemptKey, createSubagentThreadId } from './subagentThreadIds';
+import { describeErrorCauses, describeStackFrames } from './failures/subagent';
import { ActivityRecorder, activityTreeFromProjection } from './digest';
import { runWithDetachedSubagentUsage } from './subagentTaskContext';
import { SUBAGENT_COMPLETION_DELIVERY } from './subagentDelivery';
@@ -516,8 +517,9 @@ function childAgentId(request: SubagentTaskStartRequest): string | undefined {
return request.subagentType === 'self' ? request.parentAgentId : request.subagentType;
}
+/** A subagent that could not start says why in the SDK's fixed, model-facing wording. */
function publicFailureDetail(error: unknown): string {
- return error instanceof SubagentThreadPublicError
+ return error instanceof SubagentThreadPublicError || error instanceof SubagentResolutionError
? error.message.slice(0, 2_000)
: 'The child run could not be completed.';
}
@@ -1701,9 +1703,14 @@ export class SubagentThreadTaskStore extends InMemorySubagentTaskStore {
throw error;
}
logger.error('[subagentThreads] Child-thread execution failed', {
+ taskId: runtime.taskId,
detail: publicFailureDetail(error),
errorName: error instanceof Error ? error.name : typeof error,
- ...(error instanceof Error && error.stack != null ? { stack: error.stack } : {}),
+ ...(error instanceof SubagentResolutionError
+ ? { phase: error.phase, resolutionCause: error.resolutionCause }
+ : {}),
+ causes: describeErrorCauses(error),
+ frames: describeStackFrames(error),
});
if (mayPersist) {
await this.persistFailure(
diff --git a/packages/api/src/code/attachments.spec.ts b/packages/api/src/code/attachments.spec.ts
index 08e8ba8687..931037b34f 100644
--- a/packages/api/src/code/attachments.spec.ts
+++ b/packages/api/src/code/attachments.spec.ts
@@ -1,4 +1,5 @@
import { createHash } from 'node:crypto';
+import { logger } from '@librechat/data-schemas';
import { Tools, FileContext } from 'librechat-data-provider';
import { Constants as AgentConstants } from '@librechat/agents';
import type { TFile, TurnFileConsumers, CodeWorkspaceOperation } from 'librechat-data-provider';
@@ -40,18 +41,25 @@ type WorkspaceRequest = {
* In-memory stand-in for the Code API and its attached worker, implementing the
* `import_file` contract: stored objects are copied by reference, a same-digest file is left
* unchanged, a different file at the path is a conflict, `write_file` is create-only, and
- * `read_file` returns what is stored.
+ * `read_file` returns what is stored. With `missingParents`, it is a worker that predates
+ * LibreChat-AI/code-interpreter#360 on a root registered by path alone: a write or import into a
+ * folder that does not exist yet is `NOT_FOUND`, because that worker never creates one.
*/
function createFakeWorker({
objects = new Map<string, string>(),
delayMs = 0,
denyWrites = false,
truncateReads = false,
+ missingParents = false,
+ legacyCodeApi = false,
}: {
objects?: Map<string, string>;
delayMs?: number;
denyWrites?: boolean;
truncateReads?: boolean;
+ missingParents?: boolean;
+ /** A Code API that predates `NOT_FOUND` relays it as `INVALID_PATH` with the same message. */
+ legacyCodeApi?: boolean;
} = {}) {
const files = new Map<string, string>();
const requests: WorkspaceRequest[] = [];
@@ -87,6 +95,13 @@ function createFakeWorker({
if (denyWrites) {
return reply(403, { code: 'WRITE_DISABLED', error: 'File writes are disabled' });
}
+ const folder = key.slice(0, key.lastIndexOf('/') + 1);
+ if (missingParents && ![...files.keys()].some((path) => path.startsWith(folder))) {
+ return reply(422, {
+ code: legacyCodeApi ? 'INVALID_PATH' : 'NOT_FOUND',
+ error: 'Workspace path does not exist',
+ });
+ }
if (request.operation === 'write_file') {
if (files.has(key) && request.overwrite === false) {
return reply(409, { code: 'EDIT_CONFLICT', error: 'Workspace file already exists' });
@@ -703,6 +718,67 @@ describe('primeWorkspaceAttachments', () => {
expect(worker.files.get('root:.librechat/attachments/report.pdf')).toBe('pdf');
});
+ it.each([
+ ['NOT_FOUND', false],
+ ['INVALID_PATH', true],
+ ])(
+ 'tells the user to update a worker that cannot create the attachments folder (%s)',
+ async (upstreamCode, legacyCodeApi) => {
+ const warn = jest.spyOn(logger, 'warn');
+ const worker = createFakeWorker({ missingParents: true, legacyCodeApi });
+ const { deps, records } = createDeps(worker);
+ const file = remember(chatFile('report.pdf', 'pdf', worker.objects));
+ const agent = agentWith(attachedContext(), [file]);
+
+ await primeWorkspaceAttachments({ agents: [agent], deps });
+
+ expect(worker.requests.map((request) => request.operation)).toEqual(['write_file']);
+ expect(worker.files.size).toBe(0);
+ expect(agent.dynamicToolContextMap?.[Tools.execute_code]).toContain(
+ "report.pdf (attached by user): this machine's LibreChat worker cannot receive attachments yet; updating the worker enables it",
+ );
+ expect(records.every((record) => record.copy == null)).toBe(true);
+ expect(warn).toHaveBeenCalledWith(
+ '[workspaceAttachments] Could not create .librechat/attachments/.gitignore in workspace primary: unsupported',
+ {
+ type: 'WorkspaceToolHttpError',
+ reason: 'rejected',
+ upstreamStatus: 422,
+ upstreamCode,
+ },
+ );
+ warn.mockRestore();
+ },
+ );
+
+ it('logs the worker code of a refused import without its message', async () => {
+ const warn = jest.spyOn(logger, 'warn');
+ const worker = createFakeWorker();
+ const { deps } = createDeps(worker);
+ const file = remember(chatFile('report.pdf', 'pdf', worker.objects));
+ const agent = agentWith(attachedContext(), [file]);
+
+ await primeWorkspaceAttachments({
+ agents: [agent],
+ deps: { ...deps, digestFile: async () => ({ sha256: sha('other bytes'), bytes: 3 }) },
+ });
+
+ expect(agent.dynamicToolContextMap?.[Tools.execute_code]).toContain(
+ 'report.pdf (attached by user): copying it to this machine failed',
+ );
+ expect(warn).toHaveBeenCalledWith(
+ `[workspaceAttachments] Import of file ${file.file.file_id} into workspace primary failed: failed`,
+ {
+ type: 'WorkspaceToolHttpError',
+ reason: 'rejected',
+ upstreamStatus: 422,
+ upstreamCode: 'INVALID_REQUEST',
+ },
+ );
+ expect(JSON.stringify(warn.mock.calls)).not.toContain('source mismatch');
+ warn.mockRestore();
+ });
+
it('reports a worker-side write refusal instead of a path', async () => {
const worker = createFakeWorker({ denyWrites: true });
const { deps } = createDeps(worker);
diff --git a/packages/api/src/code/attachments.ts b/packages/api/src/code/attachments.ts
index 347921ea8d..d2b80b7684 100644
--- a/packages/api/src/code/attachments.ts
+++ b/packages/api/src/code/attachments.ts
@@ -33,6 +33,7 @@ import {
import { codeExecutionAuthHeaders, getCodeExecutionRouteKey } from '~/agents/execution';
import { isAttachedFileWriteDenied } from '~/agents/hitl/byom';
import { getSafeErrorMetadata } from '~/utils/errors';
+import { isWorkspacePathMissing } from './paths';
/** Workspace-relative folder chat attachments are copied into. */
export const WORKSPACE_ATTACHMENTS_DIRECTORY = '.librechat/attachments';
@@ -276,6 +277,40 @@ function classifyImportFailure(error: unknown): WorkspaceAttachmentUnavailableRe
return 'failed';
}
+/**
+ * A worker that cannot create the attachments folder reports it missing, as `NOT_FOUND` or,
+ * through an older Code API, as `INVALID_PATH` with the same message: workers before
+ * LibreChat-AI/code-interpreter#360 never created a parent on a root registered by path alone.
+ */
+function classifyIgnoreFailure(error: unknown): WorkspaceAttachmentUnavailableReason {
+ if (error instanceof WorkspaceToolHttpError && isWorkspacePathMissing(error)) {
+ return 'unsupported';
+ }
+ return classifyImportFailure(error);
+}
+
+/** What a failed workspace request may log: its outcome and the worker's error code, never a
+ * response body, a host path, or file content. */
+interface WorkspaceFailureMetadata {
+ type: string;
+ status?: number;
+ reason?: WorkspaceToolHttpError['reason'];
+ upstreamStatus?: number;
+ upstreamCode?: string;
+}
+
+function getWorkspaceFailureMetadata(error: unknown): WorkspaceFailureMetadata {
+ if (!(error instanceof WorkspaceToolHttpError)) {
+ return getSafeErrorMetadata(error);
+ }
+ return {
+ type: error.name,
+ reason: error.reason,
+ ...(error.upstreamStatus != null ? { upstreamStatus: error.upstreamStatus } : {}),
+ ...(error.upstreamCode != null ? { upstreamCode: error.upstreamCode } : {}),
+ };
+}
+
/** Admits at most `limit` tasks at once; a finishing task hands its slot to the next waiter. */
function createLimiter(limit: number): <T>(task: () => Promise<T>) => Promise<T> {
let active = 0;
@@ -519,6 +554,7 @@ async function importOne({
const reason = classifyImportFailure(error);
logger.warn(
`[workspaceAttachments] Import of file ${file.file_id} into workspace ${target.workspaceId} failed: ${reason}`,
+ getWorkspaceFailureMetadata(error),
);
return { status: 'unavailable', reason };
} finally {
@@ -672,12 +708,13 @@ async function ensureAttachmentsIgnored({
},
});
} catch (error) {
- if (classifyImportFailure(error) !== 'conflict') {
+ const reason = classifyIgnoreFailure(error);
+ if (reason !== 'conflict') {
logger.warn(
- '[workspaceAttachments] Could not create the attachments .gitignore',
- getSafeErrorMetadata(error),
+ `[workspaceAttachments] Could not create ${WORKSPACE_ATTACHMENTS_GITIGNORE} in workspace ${target.workspaceId}: ${reason}`,
+ getWorkspaceFailureMetadata(error),
);
- return classifyImportFailure(error);
+ return reason;
}
if (target.context.codeWorkspace?.operations.includes('read_file') !== true) {
return 'not_ignored';
@@ -703,8 +740,8 @@ async function ensureAttachmentsIgnored({
}
} catch (readError) {
logger.warn(
- '[workspaceAttachments] Could not read the attachments .gitignore',
- getSafeErrorMetadata(readError),
+ `[workspaceAttachments] Could not read ${WORKSPACE_ATTACHMENTS_GITIGNORE} in workspace ${target.workspaceId}`,
+ getWorkspaceFailureMetadata(readError),
);
return classifyImportFailure(readError);
}
diff --git a/packages/api/src/code/paths.ts b/packages/api/src/code/paths.ts
index d2a0bd02fc..d520382697 100644
--- a/packages/api/src/code/paths.ts
+++ b/packages/api/src/code/paths.ts
@@ -54,6 +54,11 @@ function describeUnusablePath(operation: WorkspacePathOperation, displayPath: st
return `The worker could not open ${quoted}. The file may not exist yet (a command may still be writing it), or the path is a directory or a symlink, or passes through one. List its directory to check before retrying.`;
}
+/** Whether the worker reported the path absent, in either the current or the legacy shape. */
+export function isWorkspacePathMissing(error: WorkspaceToolHttpError): boolean {
+ return getWorkspacePathRejection(error) === 'missing';
+}
+
/**
* Appends a short explanation to a worker's path rejection so the model can tell a file that
* does not exist yet from a malformed path. Other rejections are returned unchanged.