Agent Execution

Common agent execution problems and how to resolve them.

"Skill not available" error

Symptom: A step fails with a message like "skill 'X' is not available."

Cause: The agent references a capability that is not registered in the current version of ThinkForge. This can happen if the agent was created with a newer version or if something changed in the skill registry.

Solutions:

  • Update ThinkForge Desktop to the latest version
  • If the skill was renamed, recreate the agent (the creation process will select the correct current skill)

"Agent has no execution steps"

Symptom: The agent fails immediately without running any steps.

Cause: The agent definition is empty or corrupted — it has no steps in its execution pipeline.

Solution: Delete the agent and recreate it through Tool Forge. A valid agent always has at least one execution step.

AI steps fail with API errors

Symptom: Steps that use AI processing fail with messages about prompts, keys, or provider errors.

Causes:

  • No API key configured for the provider
  • API key is invalid or expired
  • Rate limits exceeded (multiple agent steps calling AI in quick succession)
  • Provider is experiencing an outage

Solution: See AI Provider Keys for detailed troubleshooting of API key issues. Make sure the profile used for agent execution has a valid key.

File write errors

Symptom: The save step fails with permission or path errors.

Causes:

  • No output folder configured on the deployment
  • The output folder does not exist or is not writable
  • The file path contains unsafe characters or patterns

Solutions:

  • Set an output folder in the deployment inspector (drag a folder or use Browse)
  • Make sure the selected folder exists and your user account can write to it
  • If file saving is not needed, disable it in agent settings (output still displays on screen)

External API integration errors

Symptom: Steps that connect to external services (GitHub, Slack, ClickUp, etc.) fail with authentication or configuration errors.

Cause: The agent uses an API integration that has not been configured with credentials or target parameters.

Solution:

  1. The first time you run an agent with API integration, it prompts you for credentials and target parameters (repository name, list ID, channel, etc.).
  2. Enter the required information — it is saved for future runs.
  3. If credentials were revoked or changed, update them in agent settings.

"No active project"

Symptom: Agent fails with a "no active project" error.

Cause: The agent was triggered (from the extension, command menu, or a trigger) without a project being open in ThinkForge.

Solution: Open a project in ThinkForge Desktop before running agents. Agents that use project memory or file operations need an active project context.

User cancelled / user rejected step output

Symptom: Agent stops mid-execution with a cancellation message.

Cause: In guided mode, you rejected a step's output, which aborts the remaining pipeline. This is expected behavior — not an error.

Solution: If you want the agent to run without pausing for approval, switch to autonomous mode in Agent Settings → Execution Mode. If you do want approval but made a mistake, simply rerun the agent.

Agent runs from the browser extension fail

Symptom: Running an agent from the Chrome extension produces an error.

Causes:

  • Desktop is not connected
  • No project is open
  • The agent referenced does not exist (stale name or ID)

Solutions:

  • Verify the extension shows "Connected" in TF Desktop settings
  • Open a project in ThinkForge Desktop
  • Refresh the agent list in the extension; ensure the agent name matches exactly

General debugging steps

When an agent fails:

  1. Read the error message on the failed step card — it usually identifies the specific problem
  2. Check that a project is open and the correct one is active
  3. Verify API keys are configured if the agent uses AI steps
  4. Confirm input sources are assigned to the deployment
  5. Try running a simpler agent to isolate whether the issue is with a specific skill or with general configuration

Related