Ask Forge Troubleshooting: RPC & LLM Errors Fixed

License Issues

Error Message

LICENSE ERROR: License file 'SchemaSmith License.lic' NOT FOUND.
Searched: ASKFORGE_LICENSE environment variable, tool directory, parent directories, and PATH.

Cause

License file not found or invalid.

Fix

Ensure SchemaSmith License.lic is accessible.

Set the ASKFORGE_LICENSE environment variable to the license file path or directory:

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

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

Or place the license file in the same directory as the ask-forge executable.
License search order: ASKFORGE_LICENSE env var, tool directory, parent directories (walks up to root), PATH directories.

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

Error Message

Enterprise license EXPIRED on 1/15/2026. Please contact sales@SchemaSmith.com for a new license.

Cause

Enterprise or standard license has passed its expiration date plus grace period.

Fix

Contact sales@SchemaSmith.com for license renewal.

Grace Periods

Standard licenses have a 7-day grace period after expiration.
Enterprise licenses have a 30-day grace period after expiration.

If the license date has passed but is still within the grace period, AskForge will start but display a warning:

WARNING: License has EXPIRED. Please contact sales@SchemaSmith.com for a new license.

Warning Message

This license is valid for testing purposes ONLY.
DO NOT USE in production environments.

Cause

Non-Enterprise license in use.

Fix

This is informational, not an error. Non-Enterprise licenses display this warning at startup. Upgrade to an Enterprise license to remove it.

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 current config: ask-forge show-config

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 FORGE_LLM_PROVIDER=OpenAI
set FORGE_LLM_API_KEY=sk-...
set FORGE_LLM_MODEL=gpt-4o

export FORGE_LLM_PROVIDER=OpenAI
export FORGE_LLM_API_KEY=sk-...
export FORGE_LLM_MODEL=gpt-4o

When FORGE_LLM_PROVIDER is set, it creates an env-override provider entry and sets it as active automatically.

Cause

The LlmProviderConfig.Validate() method checks for required fields per provider type. Validation issues are reported per provider in show-config output.

Required Fields by Provider

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`

Fix

If a provider has validation issues, it will not be initialized even when set as active. Run ask-forge show-config to see validation status for all configured providers, 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
```
Test connectivity: ask-forge test-llm-connection

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

Provider passed validation but threw an error during construction (e.g., malformed endpoint URL).

Fix

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

External Tool Issues

Error Message

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

Cause

External SchemaSmith tool (SchemaTongs, SchemaQuench, DataTongs) is not installed or not discoverable.

Tool Names by Platform

Platform	SchemaTongs	SchemaQuench	DataTongs
MSSQL	`schema-tongs`	`schema-quench`	`data-tongs`
MySQL	`mysql-tongs`	`mysql-quench`	`mysql-data-tongs`
PostgreSQL	`postgres-tongs`	`postgres-quench`	`postgres-data-tongs`

Fix

Install the appropriate SchemaSmith tool for your platform.

Configure the tool path explicitly:

ask-forge set-tool-path --platform mssql --tool schemaTongs \
  --path "/path/to/schema-tongs"

Or set a platform install path environment variable:

set SchemaSmithMSSQLPath="C:\path\to\install\dir"
set SchemaSmithMySQLPath="C:\path\to\install\dir"
set SchemaSmithPGSQLPath="C:\path\to\install\dir"

export SchemaSmithMSSQLPath="/path/to/install/dir"
export SchemaSmithMySQLPath="/path/to/install/dir"
export SchemaSmithPGSQLPath="/path/to/install/dir"

Or set a tool-specific environment variable:

set FORGE_MSSQL_SCHEMA_TONGS="C:\path\to\schema-tongs"
set FORGE_PGSQL_SCHEMA_QUENCH="C:\path\to\postgres-quench"

export FORGE_MSSQL_SCHEMA_TONGS="/path/to/schema-tongs"
export FORGE_PGSQL_SCHEMA_QUENCH="/path/to/postgres-quench"

Or ensure the tool is on your system PATH.

Tool discovery order: configured path (env var or config file) > platform install path env var > current directory > ~/.dotnet/tools > Program Files > AppData > PATH directories > which/where lookup.

Error Message

No connection configured for mssql. Use set_connection to add one:
  set_connection platform=mssql server=<host> database=<db>
  user=<user> password=<pass>

Cause

External tool invoked but no saved connection found for the platform.

Fix

Save a connection for the platform:

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

Cause

The saved connection does not have a database field set, and no --database parameter was provided.

Fix

Either update the saved connection to include a database:

ask-forge set-connection --platform mssql --database MyDB

Or pass --database MyDB as a parameter to the external tool.

Error Message

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

Cause

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

schema-tongs 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 AskForge.
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/schema-tongs

Or:

Error running /path/to/schema-tongs: <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/schema-tongs (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: forge_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.

When the config file contains invalid JSON, AskForge silently falls back to defaults. It does not crash -- it returns an empty ConfigFileWrapper.

Fix

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

Check the file directly:

type %USERPROFILE%\.forge\config.json | python -m json.tool

cat ~/.forge/config.json | python3 -m json.tool

Delete the file and let AskForge recreate defaults:

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

rm ~/.forge/config.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 %FORGE_MSSQL_SCHEMA_TONGS%
```
```
echo $FORGE_MSSQL_SCHEMA_TONGS
```
Ensure you opened a new terminal after setting system-level environment variables.
Variable names are case-sensitive on macOS/Linux. Use exact names:
- FORGE_MSSQL_SCHEMA_TONGS, FORGE_PGSQL_SCHEMA_QUENCH, etc.
- FORGE_LLM_PROVIDER, FORGE_LLM_API_KEY, FORGE_LLM_MODEL
For per-provider overrides, the variable names are different:
- FORGE_OPENAI_API_KEY, FORGE_OPENAI_MODEL
- FORGE_ANTHROPIC_API_KEY, FORGE_ANTHROPIC_MODEL
- FORGE_OLLAMA_ENDPOINT, FORGE_OLLAMA_MODEL

Cause

No connection configured for the requested platform.

Fix

List all connections: ask-forge list-connections

Add a connection:

ask-forge set-connection --platform mssql --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 current trust level: ask-forge show-config

Increase trust level in the config file:

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

Or override per invocation:

ask-forge --trust-level operator run-schema-tongs --platform mssql

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 mssql --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

AskForge not on PATH, or command name 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.

Renamed Commands

Old command names have been replaced. If you get an unrecognized command error, check these common renames:

Old Name	New Name
`context`	`show-context`
`tables`	`list-tables`
`analyze`	`review-schema`
`suggest`	`suggest-changes`
`generate`	`generate-migration`

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

AskForge 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 active configuration, LLM provider status, trust level
`ask-forge show-context`	Display current product/template context
`ask-forge list-connections`	List all saved database connections
`ask-forge test-llm-connection`	Test connectivity to the active LLM provider
`ask-forge view-log --log_path <path>`	View the tail of an external tool log file

Troubleshooting

License Issues

AskForge exits immediately with code 2

Error Message

Cause

Fix

License expired

Error Message

Cause

Fix

Grace Periods

"Test environment only" warning

Warning Message

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

Tool Names by Platform

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