PARAS MADAN
All writing

Latest in AI

Catch ignored settings in the Claude Agent SDK for TypeScript

Handle settings_not_in_effect in Claude Agent SDK 0.3.330 and separate a skipped configuration from an invalid JSON input or a normal agent response.

Your app can show a successful Claude response even when part of its configuration did not load. If the UI only renders assistant text, the person operating the app may never see that warning.

Claude Agent SDK for TypeScript 0.3.330, released November 20, gives embedding apps a specific warning tag for settings that are not in effect. It also changes how the SDK handles an unparsable inline settings string. Those are two signals your app can surface without dumping a session transcript into its logs.

Keep the warning separate from the result

The TypeScript message reference defines the event as a system message with subtype informational and tag settings_not_in_effect. The warning can cover settings supplied by your app or settings from user, project or local files. Anthropic notes that not every invalid value will produce it.

Match the typed tag rather than searching assistant text for a phrase that could change. For example, this classifier can sit in your existing message loop:

import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";

export function hasSkippedSettings(message: SDKMessage): boolean {
  return (
    message.type === "system" &&
    message.subtype === "informational" &&
    message.tag === "settings_not_in_effect"
  );
}

On a match, show a short operator notice and increment a counter for that tag. Do not include the raw content, configuration, prompt, tool arguments or transcript in centralized logs. The tag and SDK version are enough to tell you whether a rollout made these warnings more common.

Handle invalid input on the error path

The SDK accepts inline JSON through the settings option as well as a settings object or a file path. In 0.3.330, query() fails when the supplied JSON string cannot be parsed. Do not assume that this arrives as an informational message. Wrap query creation and message iteration in the same error boundary.

If your application generates inline JSON itself, parse it before invoking the SDK and validate the values your feature requires. Report a generic configuration error to the operator when that fails. That check is useful even if your message loop already recognizes the new warning: syntax rejection and a setting being skipped are different failure modes.

Inspect the effective settings carefully

The settings reference explains why configuration can come from different levels. Record which directory the app uses and which sources it intends to load before investigating a mismatch. Check the real session rather than assuming a successful run from your terminal used the same inputs.

The SDK's alpha resolveSettings() helper can give you effective values and the source of each top-level key for a directory. It is a diagnostic snapshot, not a substitute for live policy: for example, it does not fetch server-managed settings by itself. Use it to compare the one harmless key you are investigating, not to print the full merged configuration.

Use a disposable fixture before rollout

Test the classifier with a synthetic warning event, a normal informational message and an assistant response. Only the first should raise your settings notice. Separately pass an invalid inline JSON string in a disposable project, with no real credentials or operational commands in the fixture, and check that the error path produces your generic notice.

Then try a read-only canary against a test project with the expected settings and check the behavior the setting is meant to control. No warning is not a guarantee that every setting took effect. Your app should rely on explicit configuration checks and its own controls where the setting is required, not on silence in a stream.

Document what operators can actually check

I'm Paras. I work at the intersection of AI, engineering and distribution.

I help AI and developer tool teams turn SDK changes into technical writing and product stories builders can use.

Book a 30-minute call.