n8n - 💡(How to fix) Fix Exporting workflows with AI Gateway-managed credentials throws a ZodError [1 pull requests]

Summary

Package export currently rejects valid workflows that use AI Gateway-managed credentials.

WorkflowSerializer.serialize() passes workflow.nodes directly into serializedWorkflowSchema.parse(...), but the serialized workflow schema currently requires every credential reference to have id: string.

// packages/cli/src/modules/n8n-packages/spec/serialized/workflow.schema.ts
const credentialReferenceSchema = z.object({
	id: z.string(),
	name: z.string(),
});

// packages/cli/src/modules/n8n-packages/entities/workflow/workflow.serializer.ts
return serializedWorkflowSchema.parse({
	id: workflow.id,
	name: workflow.name,
	nodes: workflow.nodes,
	...
});

That does not match the workflow credential shape used elsewhere in the repo for AI Gateway-managed credentials.

Why this is valid workflow data

INodeCredentialsDetails explicitly allows id: string | null:

// packages/workflow/src/interfaces.ts
export interface INodeCredentialsDetails {
	id: string | null;
	name: string;
	__aiGatewayManaged?: boolean;
}

The frontend also creates AI Gateway-managed credentials using id: null:

// packages/frontend/editor-ui/src/features/credentials/components/NodeCredentials.vue
credentials[credentialType] = { id: null, name: '', __aiGatewayManaged: true };

There are existing tests that use and validate this exact shape, for example:

// packages/cli/src/workflows/__tests__/workflow.service.ee.test.ts
googlePalmApi: { id: null, name: '', __aiGatewayManaged: true },

and editor tests also use the same runtime value.

Reproduction

Create or load a workflow containing a supported AI node with an AI Gateway-managed credential:

credentials: {
	googlePalmApi: {
		id: null,
		name: '',
		__aiGatewayManaged: true,
	},
}

Then run workflow package export.

Actual behavior

Export fails with a Zod validation error on the credential id, e.g.

ZodError: [
  {
    code: "invalid_type",
    expected: "string",
    received: "null",
    path: ["nodes", 0, "credentials", "googlePalmApi", "id"]
  }
]

Expected behavior

Valid workflows using AI Gateway-managed credentials should export successfully.

Additional issue: preserving __aiGatewayManaged

Even if id is changed to nullable, the serialized schema also needs to preserve __aiGatewayManaged.

Downstream code relies on that marker when id is null, for example:

• packages/workflow/src/node-validation.ts
• packages/cli/src/credentials-helper.ts
• packages/cli/src/workflow-helpers.ts

If export/import drops __aiGatewayManaged, a null-id credential can be misclassified as not configured or treated like a normal DB-backed credential.

Suggested fix

Allow nullable credential ids and preserve the AI Gateway marker in the serialized workflow schema, e.g.

const credentialReferenceSchema = z.object({
	id: z.string().nullable(),
	name: z.string(),
	__aiGatewayManaged: z.boolean().optional(),
});

If the intent is to avoid losing additional valid node fields during export, it may also be worth considering whether parts of the node schema should be more permissive.