serverless/serverless · error · Error

toolSchema must be a file path string or array of tool defin

Error message

toolSchema must be a file path string or array of tool definitions

What it means

resolveToolSchema() only accepts two shapes for toolSchema: a string (file path) or an array (inline tool definitions). Any other type (number, plain object, boolean) reaches the terminal throw at the end of the function.

Source

Thrown at packages/serverless/lib/plugins/aws/bedrock-agentcore/compilers/gatewayTarget.js:269

      })),
    }
  }

  // Inline array
  if (Array.isArray(toolSchema)) {
    return {
      InlinePayload: toolSchema.map((tool) => ({
        Name: tool.name,
        Description: tool.description,
        InputSchema: transformSchemaToCloudFormation(tool.inputSchema),
        ...(tool.outputSchema && {
          OutputSchema: transformSchemaToCloudFormation(tool.outputSchema),
        }),
      })),
    }
  }

  throw new Error(
    'toolSchema must be a file path string or array of tool definitions',
  )
}

/**
 * Build Lambda target configuration
 * New syntax: { function: 'functionName' | { name, arn }, toolSchema: [...] | 'file.json' }
 */
export function buildLambdaTarget(config, serviceDir) {
  const lambdaArn = resolveFunctionArn(config.function)
  const toolSchema = resolveToolSchema(config.toolSchema, serviceDir)

  return {
    Mcp: {
      Lambda: {
        LambdaArn: lambdaArn,
        ToolSchema: toolSchema,
      },

View on GitHub (pinned to b9d7ea51c8)

Solutions

If inline, wrap the tool(s) in an array: toolSchema: [ { ... } ].
If referencing a file, use a string path.
Do not pass a single object, number, or boolean as toolSchema.

Example fix

# before
toolSchema:
  name: doThing
  description: x
  inputSchema: { type: object }
# after
toolSchema:
  - name: doThing
    description: x
    inputSchema:
      type: object

Defensive patterns

Strategy: type-guard

Validate before calling

if (typeof toolSchema !== 'string' && !Array.isArray(toolSchema)) {
  throw new Error('toolSchema must be a string file path or an array of tool definitions');
}

Type guard

function isToolSchema(v) {
  return typeof v === 'string' || Array.isArray(v);
}

Prevention

Always wrap a single inline tool in an array.
Use the framework's config schema to enforce array-or-string.
Add a fixture in tests for the single-object case to catch regressions.

When it happens

Trigger: toolSchema set to a single inline tool object instead of an array; a numeric or boolean value; an object that should have been a file-path string.

Common situations: User wraps a single tool in {} instead of [{}]; passes a YAML mapping where the schema expects a list.

Related errors

AI-assisted analysis of serverless/serverless@b9d7ea51c8 (2026-08-13). Data as JSON: /api/errors/ec69d66a99b97081. Report an issue: GitHub.