Troubleshoot Ask Forge Setup & Runtime Errors

License Issues

Error Message

When no license file is found anywhere in the search path:

LICENSE ERROR: No license file found. ForgeBarrett requires an AskForge license.

When a license file is found but has no active AskForge add-on (a different add-on, or an AskForge add-on expired past its grace period):

LICENSE ERROR: No active AskForge add-on found in license.

Cause

Either no license file was found, or the license that was found has no active AskForge add-on. Ask Forge requires a valid license with an active AskForge add-on to run.

Fix

Ensure SchemaSmith License.lic is accessible.

Set the SCHEMASMITH_LICENSE environment variable to the license file path or its directory:

set SCHEMASMITH_LICENSE="C:\path\to\SchemaSmith License.lic"

export SCHEMASMITH_LICENSE="/path/to/SchemaSmith License.lic"

Or place the license file in the same directory as the ask-forge executable.
License search order: the --LicenseFile: argument, the SCHEMASMITH_LICENSE environment variable, the tool directory, parent directories (walks up to root), then PATH directories.

Both the CLI and MCP server validate the license at startup. If the license is missing or invalid, the process exits with code 2 before any commands run.

Behavior

The AskForge add-on includes a 30-day grace period after its expiration date. While the add-on is expired but still within the grace period, Ask Forge continues to run normally. Once the grace period ends, the add-on is no longer active and Ask Forge exits at startup with the same code-2 error as a missing add-on:

LICENSE ERROR: No active AskForge add-on found in license.

Cause

The AskForge add-on's expiration date plus its 30-day grace period has passed.

Fix

Contact sales@SchemaSmith.com for license renewal.

LLM Provider Issues

Cause

No provider is set as active, or llm.active points to a provider name that does not exist in the llm.providers dictionary.

This message appears when attempting any LLM operation: sending prompts, testing connections, or listing models.

Fix

Check the active provider — launch ask-forge and run llm, or inspect ~/.schemasmith/askforge.json directly

Set an active provider in the config file:

{
  "llm": {
    "active": "your-provider-name",
    "providers": {
      "your-provider-name": {
        "type": "openAI",
        "apiKey": "sk-...",
        "model": "gpt-4o"
      }
    }
  }
}

Or use environment variables for quick setup:

set SCHEMASMITH_LLM_PROVIDER=openAI
set SCHEMASMITH_LLM_API_KEY=sk-...
set SCHEMASMITH_LLM_MODEL=gpt-4o

export SCHEMASMITH_LLM_PROVIDER=openAI
export SCHEMASMITH_LLM_API_KEY=sk-...
export SCHEMASMITH_LLM_MODEL=gpt-4o

When SCHEMASMITH_LLM_PROVIDER is set, Ask Forge creates a synthetic provider named env-override and activates it automatically.

Cause

Ask Forge validates each configured provider's required fields at startup. Validation issues are reported per provider by the interactive llm command (launch ask-forge, then run llm).

Required Fields by Provider

Every provider requires type and model. The table below lists the additional fields each type needs.

Provider	Required Fields
Ollama	`endpoint`, `model`
OpenAI	`apiKey`, `model`
Azure OpenAI	`endpoint`, `apiKey`, `deployment`, `model`
Anthropic	`apiKey`, `model`
Groq, Gemini, Mistral, DeepSeek, xAI	`apiKey`, `model`
Custom	`model` (no `apiKey` or `endpoint` enforced)

Fix

If a provider has validation issues, it will not be initialized even when set as active. Launch ask-forge and run llm to list every configured provider with its validation status (invalid ones are flagged), then add the missing required fields.

Cause

Invalid API key, wrong endpoint, or network issue.

Fix

Verify the API key is correct and not expired.
If using ${ENV_VAR} substitution in apiKey, verify the referenced environment variable is set:
```
# Config uses: "apiKey": "${ANTHROPIC_API_KEY}"
echo $ANTHROPIC_API_KEY
```
Check the endpoint URL (especially for Azure OpenAI and custom providers).
For Ollama, verify the server is running:
```
curl http://localhost:11434/api/tags
```
Confirm the provider initialized cleanly by launching ask-forge and running llm — Ask Forge runs a live connection test when you configure or switch providers and reports the result there (the welcome banner also shows it for the active provider).

Cause

The type field in the provider config is set to an unrecognized value.

Supported Types

Ollama, OpenAI, AzureOpenAI, Anthropic, Groq, Gemini, Mistral, DeepSeek, XAi, Custom

Cause

The provider passed validation but failed while initializing (e.g., a malformed endpoint URL).

Fix

Check the provider configuration values. The error message includes the underlying exception detail.

External Tool Issues

Error Message

Could not find 'SchemaTongs' executable. Please ensure SchemaSmith tools are installed and available in PATH.
Or set the SchemaSmithPath environment variable to the install directory.

Cause

The external SchemaSmith tool is not installed or not discoverable. The three tools are single cross-platform binaries — SchemaTongs, SchemaQuench, and DataTongs (with a .exe suffix on Windows). The same binary serves SQL Server, PostgreSQL, and MySQL.

Fix

Install the SchemaSmith tools.
Point the SchemaSmithPath environment variable at the install directory:
```
set SchemaSmithPath="C:\path\to\install\dir"
```
```
export SchemaSmithPath="/path/to/install/dir"
```
Or ensure the tools are on your system PATH.

Tool discovery order: the executable's own directory, then the SchemaSmithPath environment variable, then Program Files\SchemaSmith\SchemaSmith, then your PATH.

Error Message

No connection configured for sqlserver. Use manage_connection to add one:
  manage_connection action=set platform=sqlserver server=<host> database=<db> user=<user> password=<pass>

Cause

An external tool was invoked but no saved connection was found for the platform.

Fix

Save a connection for the platform:

ask-forge manage-connection --action set --platform sqlserver \
  --server localhost --database MyDB --user sa --password "..."

Cause

SchemaTongs (schema) and DataTongs (reference data) extract from a specific source database, so they require one — set either a database on the saved connection or a --database parameter. SchemaQuench does not need one: it connects at the server level, and the DatabaseIdentificationScript in your product's templates identifies which databases to deploy to.

Fix

Provide the source database. Either update the saved connection to include one:

ask-forge manage-connection --action set --platform sqlserver --database MyDB

Or pass --database MyDB to the extraction tool when you run it.

Error Message

Operation timed out after 5.0 minutes.
(showing last 50 of 2341 lines)
...
Full output: /path/to/Logs/SchemaTongs - Progress.log

Cause

The tool takes longer than the 5-minute default timeout.

Fix

This can happen with large databases. The process is killed after timeout. Check the progress log for how far it got:

ask-forge view-log --log-path "/path/to/Logs/SchemaTongs - Progress.log"

Consider extracting a subset of objects using --object-filter to reduce scope.

Error Message

SchemaTongs failed with exit code 1:
(showing last 50 of 120 lines)
...
Full output: /path/to/Logs/SchemaTongs - Progress.log

Cause

Connection details invalid, database unreachable, permission issue, or tool-specific error.

Fix

Verify the connection details work independently (e.g., via sqlcmd, psql, or mysql).
Check database connectivity from the machine running Ask Forge.
Ensure the database user has sufficient permissions.

Review the full log:

ask-forge view-log --log-path "/path/to/Logs/SchemaTongs - Progress.log"

Error Messages

Failed to start process: /path/to/SchemaTongs

Or:

Error running /path/to/SchemaTongs: <exception detail>

Cause

The tool path exists but the executable cannot be launched (permissions, architecture mismatch, missing runtime).

Fix

Verify the file is executable: chmod +x /path/to/SchemaTongs (macOS/Linux).
Check architecture compatibility (arm64 vs. x64).
Ensure the .NET runtime is installed if the tool requires it.

MCP Server Issues

Cause

Server path incorrect, license validation failed, or configuration error.

Fix

Test the server directly in a terminal and check stderr for errors:
```
dotnet ForgeBarrett.Mcp.dll
```
The MCP server writes diagnostics to stderr. License errors, startup messages, and tool counts all appear there.
Verify the path in your MCP client config matches the actual installation path.
Check for license errors (exit code 2 means license failure).
Look for the startup message on stderr: MCP Server starting on stdio with N tools registered...

Response Message

This operation requires confirmation.

Tool: schemasmith_apply_change
Tier: Modify (Modifies files or creates packages)
Description: ...

To execute this tool, add 'confirm: true' to the arguments.

Cause

Modify and External tier tools require explicit confirmation via the confirm parameter.

Fix

The MCP client (AI assistant) must include "confirm": true in the tool call arguments for Modify and External tier tools. This is by design -- these tools modify files or invoke external processes.

This is not an error. Tools at Tier 3 (Modify) and Tier 4 (External) append [Requires confirm: true] to their descriptions so AI clients know to pass the confirmation flag.

Configuration Issues

Cause

Invalid JSON in the config file.

Ask Forge does not crash on a malformed config file. Running ask-forge show-config reports the specific parse error — for example, Failed to read configuration: Invalid character after parsing property name (with the line and position) — which pinpoints the syntax problem.

Fix

Validate the JSON syntax. Common issues: trailing commas, missing quotes, unescaped characters.

Check the file directly:

type %USERPROFILE%\.schemasmith\askforge.json | python -m json.tool

cat ~/.schemasmith/askforge.json | python3 -m json.tool

Delete the file and let Ask Forge recreate defaults:

del %USERPROFILE%\.schemasmith\askforge.json
ask-forge show-config

rm ~/.schemasmith/askforge.json
ask-forge show-config

Use ask-forge show-config to verify what configuration is currently active.

Cause

Shell session not refreshed, variable name is wrong, or config precedence issue.

Precedence Order Highest Wins

Explicit CLI parameter > environment variable > config file.

Fix

Verify the variable is set in your current shell:
```
echo %SCHEMASMITH_LLM_PROVIDER%
```
```
echo $SCHEMASMITH_LLM_PROVIDER
```
Ensure you opened a new terminal after setting system-level environment variables.
Variable names are case-sensitive on macOS/Linux. Use exact names:
- SCHEMASMITH_LLM_PROVIDER, SCHEMASMITH_LLM_API_KEY, SCHEMASMITH_LLM_MODEL
- SchemaSmithPath (install directory for the external SchemaTongs / SchemaQuench / DataTongs binaries)
For per-provider overrides, the variable names are different:
- SCHEMASMITH_OPENAI_API_KEY, SCHEMASMITH_OPENAI_MODEL
- SCHEMASMITH_ANTHROPIC_API_KEY, SCHEMASMITH_ANTHROPIC_MODEL
- SCHEMASMITH_OLLAMA_ENDPOINT, SCHEMASMITH_OLLAMA_MODEL

Cause

No connection configured for the requested platform.

Fix

List all connections: ask-forge list-connections

Add a connection:

ask-forge manage-connection --action set --platform sqlserver \
  --server localhost --database MyDB --user sa --password "..."

Permission & Trust Issues

Cause

The current trust level does not permit the requested tool tier.

Trust Level Permissions

Trust Level	Allowed Tiers
`observer`	Tier 1 (ReadOnly) only
`assistant` default	Tier 1 (ReadOnly) + Tier 2 (Generate)
`operator`	All tiers (ReadOnly, Generate, Modify, External)

Fix

Check the current trust level — launch ask-forge and run config, or read agent.trustLevel in ~/.schemasmith/askforge.json

Increase the trust level in the config file:

{
  "agent": {
    "trustLevel": "operator"
  }
}

Or change it at runtime in the REPL:
```
config agent trustlevel operator
```

Cause

A Tier 3 or 4 tool was invoked without --yes in a non-interactive context.

Fix

Pass --yes to bypass confirmation:

ask-forge run-schema-tongs --platform sqlserver --yes

Or set the confirmation level in config:

{
  "agent": {
    "confirmationLevel": "never"
  }
}

Confirmation Level Values

always default -- prompts for Modify and External tiers
external -- prompts for External tier only
never -- no prompts

General Issues

Cause

Ask Forge is not on PATH, or the command name has a typo.

Fix

Verify installation: ask-forge --version
If not found, add the install directory to PATH.
Commands use kebab-case: list-tables, not listTables or list_tables.
List every available command with ask-forge --help.

Cause

Command requires a product or template context but none is set.

Fix

Use --product and --template flags:

ask-forge list-tables --product ./MyProduct --template Default

Or navigate first in REPL mode:

> navigate-context --product ./MyProduct --template Default

Ask Forge attempts auto-detection from the current directory at startup. Run ask-forge from within your schema product directory.

Cause

Current directory does not contain a Product.json file, and no previous session was saved.

Fix

Either pass --product /path/to/product explicitly, or cd into a directory that contains Product.json before running ask-forge.

Diagnostic Commands

These commands help diagnose configuration and connectivity issues:

Command	Purpose
`ask-forge show-config`	Display the configuration file path and saved database connections
`ask-forge show-context`	Display current product/template context
`ask-forge list-connections`	List all saved database connections
`ask-forge view-log --log-path <path>`	View the tail of an external tool log file
`ask-forge` → `llm`	In interactive mode: show the active LLM provider, its live connection-test result, and all configured providers with validation status
`ask-forge` → `config`	In interactive mode: show LLM config, trust level, saved connections, and external tool resolution

Troubleshooting

License Issues

Ask Forge exits immediately with code 2

Error Message

Cause

Fix

License expired

Behavior

Cause

Fix

LLM Provider Issues

"No LLM provider is configured"

Cause

Fix

Provider validation errors at startup

Cause

Required Fields by Provider

Fix

LLM connection failures / API errors

Cause

Fix

"Provider type is not supported"

Cause

Supported Types

"Failed to initialize provider"

Cause

Fix

External Tool Issues

Tool executable not found

Error Message

Cause

Fix

No connection configured

Error Message

Cause

Fix

Missing database name

Cause

Fix

External tool execution timeout

Error Message

Cause

Fix

External tool returns non-zero exit code

Error Message

Cause

Fix

"Failed to start process"

Error Messages

Cause

Fix

MCP Server Issues

MCP server not responding / tools not appearing

Cause

Fix

Confirmation required for Tier 3/4 tools

Response Message

Cause

Fix

Tool descriptions show "[Requires confirm: true]"

Configuration Issues

Config file not loading

Cause

Fix

Environment variables not taking effect

Cause

Precedence Order Highest Wins

Fix

Connection not found

Cause

Fix

Permission & Trust Issues

Tool tier not allowed

Cause

Trust Level Permissions

Fix

Confirmation prompt blocking in scripts/CI

Cause

Fix

Confirmation Level Values