Claude Code Subagent Not Working? Common Problems and Fixes

If your Claude Code subagent is not working, first find out where the problem happens: loading the agent, asking Claude to use it, or running its task. Each needs a different fix.

A subagent is a helper that handles a task for your main Claude session. A file can look correct in your editor while the helper still fails to load. A helper can also load successfully but lack the tools needed for your request.

This guide starts with a small test. It then explains how to investigate missing agents, skipped delegation, permission errors, model problems, and weak results.

If you have not created an agent yet, start with the complete subagent setup tutorial.

Why is my Claude Code subagent not working?

Use the symptom to choose your first check:

What you see	First thing to check
Claude cannot find the helper	Agent file, project folder, and configuration
Claude answers without delegating	Whether your prompt names the helper explicitly
The helper starts but cannot complete the job	Tool access and the exact error
The helper cannot edit or run tests	Whether those actions are part of its allowed role
It uses an unexpected model	Model settings and account restrictions
It produces a vague answer	Task scope, input files, and required output

Change one thing at a time. If you rename the agent, switch models, and rewrite permissions together, you will not know which change solved the problem.

Start with a small diagnostic test

Use an empty practice folder rather than changing your production project. You only need a text editor and a working Claude Code installation.

In your terminal, check the installed version:

claude --version

The local CLI checked while preparing this article was 2.1.295. Some commands below require a recent version. Follow the update method for your installation if you are using an older release; see Claude Code troubleshooting.

Create two small files

Create this structure in your editor:

subagent-check/
  .claude/
    agents/
      article-checker.md
  sample.txt

Put this single line in sample.txt:

The sample order total is 42.

Put the following in .claude/agents/article-checker.md. Copy the contents without the surrounding Markdown code fence:

---
name: article-checker
description: Reads sample.txt and reports its stated order total. Use when asked to check the diagnostic sample.
tools: Read
model: inherit
---

Read only sample.txt in the current project.
Report the order total stated in that file.
Mention the filename as evidence.
Do not edit files or run commands.
If the file cannot be read, report the error instead of guessing.

This is an original test fixture, not a useful business agent. Its job is deliberately small: read one file and report one number.

Validate the file

Open a terminal in subagent-check and run:

claude plugin validate .claude/agents

Despite its name, this command can check agent directories. That support requires version 2.1.233 or later. A successful check does not prove that delegation or model access works. The official subagent reference documents this check and its limitations.

Ask Claude to use the helper

Start Claude from the same folder:

claude

Paste this into the Claude conversation:

Delegate the diagnostic sample check to the article-checker subagent.
Have it read sample.txt and report the stated order total with the filename.
Do not answer by reading the file yourself. Do not change any files.

Check the transcript for the helper being invoked. The expected result is 42, with sample.txt named as evidence. That is an expected result, not a recorded model response.

If this works but your original helper does not, compare their files and requested actions. If even this fails, record the exact error before changing anything else.

1. Claude cannot find the custom agent

Symptom: your prompt names the helper, but Claude cannot use it.

Fix: inspect the actual files, not just the editor tab’s title. Check the project location, .md extension, and frontmatter. The opening --- must be the first line; name and description are required. Malformed YAML can cause the file to be skipped. See the agent-file loading rules.

For the diagnostic example, run these from its project folder.

macOS/Linux, in Bash or Zsh:

pwd
ls -la .claude/agents
cat .claude/agents/article-checker.md

Windows PowerShell:

Get-Location
Get-ChildItem -Force .claude/agents
Get-Content .claude/agents/article-checker.md

Compare the output with the example above. A common copying mistake is saving the code-fence line before the first ---. Another is creating article-checker.md.txt.

For your real agent, inspect the file locally without sharing private instructions or credentials.

Verify: validate again, restart Claude in the intended folder, and repeat the explicit delegation prompt. A restart is especially useful if the agents directory was created after the session began.

2. The agent exists, but Claude does not use it automatically

Symptom: Claude completes the task itself.

Fix: first request the helper by name. If that works, investigate task routing rather than treating it as a loading failure.

A description such as “Expert assistant” gives little guidance. Try a specific description of when to use the helper:

description: Reviews named checkout files for incorrect discount calculations. Use for a calculation review without edits.

Anthropic recommends focused descriptions and warns that too many overlapping helpers can make selection less reliable. Automatic delegation uses model judgment, so a description is not a guarantee that every matching request will trigger it. See Anthropic’s subagent guidance.

Verify: send one request naming the helper, then one describing its task without naming it. Record whether delegation occurred in each case. Do not infer that a helper ran solely because the answer sounds like its instructions.

3. The helper starts, but cannot use a tool

Symptom: it reports an unavailable tool or refuses the requested action.

Fix: compare the task with the configured tool list. Our diagnostic helper has only Read. Asking it to search the web, run npm test, or update a file does not match that configuration.

For a review-only task, change the request:

Inspect the named file and suggest test cases as text.
Do not run tests or claim that they passed.

If execution is genuinely needed, deliberately configure the appropriate tools and permissions. Avoid removing every restriction just to see whether the error disappears.

A tool being available and an action being permitted are separate checks. Review the Claude Code permissions documentation.

Verify: run the smallest action you intended to allow. For example, reading sample.txt confirms a file read; it does not confirm terminal or network access.

4. A permission rule blocks the agent

Symptom: the failure names a denied action or policy.

Fix: inspect the active rules through /permissions inside Claude. Look for the specific blocked action, including delegation through the Agent tool. Check whether the rule is personal, project-level, or managed by your organization.

Do not assume editing one project file overrides every other setting. Claude has multiple configuration scopes and precedence rules. See settings files and precedence.

If a restriction is intentional, keep it and adjust the task. If it is an accidental rule you control, narrow the correction to that action. For organization-managed restrictions, involve the administrator rather than attempting a bypass.

Verify: rerun the same small task after the approved correction. Keep a record of the rule changed so it can be reviewed later.

For secret-handling boundaries, read how to protect API keys when using coding agents.

5. The agent uses the wrong model or reports model access errors

Symptom: the task starts with an unexpected model, or the requested model is unavailable.

Fix: distinguish the model you requested from the model your account and configuration allow. Check the agent’s model field, launch options, relevant environment settings, and any organization model policy.

For the diagnostic file, keep model: inherit rather than introducing a model you have never used successfully. If the test passes, try the desired model as a separate change.

Model aliases and availability depend on configuration and provider. Use the official model configuration reference rather than copying an old model ID from an unrelated tutorial.

Verify: inspect the running task’s model in /tasks on supported versions and read any substitution warning. Compare the same small input before and after changing the model.

If the error is about authentication, billing, rate limits, or network access, address that error directly. Renaming the agent will not resolve it.

6. The agent runs, but its answer is vague or incomplete

Symptom: you get broad advice instead of a useful result.

Fix: give the helper three things: the input, the intended rule, and the required output.

Compare these requests:

Review my app and improve it.

Review src/cart/discount.js without editing it.
The discount argument is a percentage from 0 to 100.
For each confirmed bug, provide the line number, example input,
actual behavior, and expected behavior. List unanswered questions separately.

The second request makes the review checkable. A helper cannot infer every business rule from code alone, especially when that code may contain the bug.

Verify: open the cited lines and test the reported example. If the claim cannot be reproduced, ask what evidence supports it. A confident answer is not a passing test.

7. An old tutorial shows a different agents menu

Symptom: a command does not open the screen shown in a video.

Fix: compare the tutorial’s version with claude --version. Current docs describe file-based custom agents; older versions used an interactive /agents wizard. The terminal command claude agents manages background sessions and serves a different purpose. See the CLI reference.

Use the diagnostic file in this article instead of depending on a particular menu layout.

Verify: test the configuration and request the helper explicitly. Judge success by the actual delegation and result, not by whether your interface matches an old screenshot.

Still stuck? Collect a useful problem report

Record the following before asking for help:

Claude Code version:
Operating system:
Where I started Claude:
Agent filename and name field:
Exact prompt:
Exact error, with secrets removed:
Did the small diagnostic example work?:
What changed before the problem started?:

The CLI also provides claude doctor for installation and settings diagnostics. For a local debug session, claude --debug enables diagnostic logging. Review logs before sharing them; they can contain project information. These options are documented in the CLI reference.

Common questions

Should I reinstall Claude Code first?

Start with the small test and exact error. Reinstalling does not correct a malformed project file or an unsuitable task. Installation diagnostics can help determine whether reinstalling is relevant.

Does a successful validator result mean the agent will work?

No. Configuration validation and task execution are different checks. Confirm that the helper is invoked, can access the intended input, and returns a result you can verify.

Should I disable permission checks to fix it?

No. Identify the blocked operation and decide whether it belongs in the task. A review-only helper does not need broad system access to inspect a sample text file.

What should I try after the diagnostic example works?

Move to one real file with a clear expected result. Then expand the task gradually. The subagent setup guide and 10 practical use cases provide starting points. More related articles are in the Claude Code collection.