Problems you can hit with the Ask Forge CLI and MCP server, organized by what you see: the message, its cause, and the fix.
By the SchemaSmith Team · Last reviewed
Find your problem, understand the cause, apply the fix.
Start by checking which build you have. Each executable prints its release, then + and the commit it was built from, and exits:
ask-forge --version
ForgeBarrett.Mcp --version
The MCP server prints its version before it checks for a license. The CLI checks your license and reads your settings file first, so ask-forge --version also tells you whether both are in order. If either is not, it prints one of the errors below instead.
The CLI and the MCP server check the license when they start, and print the same messages. The MCP server writes them to standard error, never to the stream your AI assistant reads. Each error below stops the executable with exit code 2.
LICENSE ERROR: No license file found. ForgeBarrett requires an AskForge license.
Cause: Ask Forge found no license file anywhere it looks. A path you give it directly can name any file, but in a folder it searches, the file must be named SchemaSmith License.lic.
Fix: Put the file beside the executables, or point SCHEMASMITH_LICENSE at the file or the folder that holds it. For the MCP server, set the variable in your client's configuration for the server. License File lists everywhere Ask Forge looks, in order.
$env:SCHEMASMITH_LICENSE = "C:\path\to\SchemaSmith License.lic"
export SCHEMASMITH_LICENSE="/path/to/SchemaSmith License.lic"
LICENSE ERROR: The license file could not be read: <reason>
Cause: Ask Forge found a license file but could not use it: the file is damaged, cannot be opened, or was signed with a different key. The reason names the file it found.
Fix: Replace it with the license file you were issued. If the file named is not the one you meant, it sits somewhere Ask Forge looks before the place you put yours, and the first file found is the one used.
LICENSE ERROR: No active AskForge add-on found in license.
Cause: The license file is valid, but it does not include the Ask Forge add-on.
Fix: Check that the file is the license issued for Ask Forge, and not one issued for something else.
LICENSE ERROR: License for AskForge expired <date>, please renew. Contact sales@SchemaSmith.com.
Cause: The Ask Forge add-on's expiration date has passed, and so has its grace period.
Fix: Replace the file with your renewed license.
LICENSE WARNING: License for AskForge renews <date>. New license file will arrive via email.
LICENSE WARNING: License for AskForge expires <date>. Please ensure your license file is renewed.
LICENSE WARNING: LICENSE EXPIRED for AskForge. Grace period ends <date>.
Cause: Ask Forge keeps working through these. The first appears from 60 days before the expiration date, the second in the last 30 days, and the third during the 30-day grace period after it. --quiet does not hide them.
Fix: Renew before the grace period ends.
ERROR: The SchemaSmith settings file '<path>' could not be read: <reason>. Nothing was saved, because saving would overwrite it. Fix or move the file and try again.
Cause: askforge.json, or the file you named with --config, exists but cannot be read: it is not valid JSON, or it holds a value Ask Forge cannot read, such as an LLM provider type it does not know. The reason gives the line and position. The CLI refuses rather than starting on defaults. Every save rewrites the whole file, so carrying on would overwrite your configuration, including the tokens that are the only way to find your credentials again. It exits with code 1.
Fix: Correct the JSON, or move the file aside and let Ask Forge create a fresh one the next time you save a setting. A missing or empty file is not an error.
The MCP server does not stop for this. Run show_config through schemasmith_execute_tool and it reports Failed to read configuration: and the reason, and manage_connection refuses with Failed to save configuration: and leaves the file as it is.
The trust level was not changed to Operator: the SchemaSmith settings file '<path>' could not be written - Access to the path '<path>' is denied.
The settings file is unchanged, and this session is still at trust level Assistant.
Check that you have permission to write that file and that it is not marked read-only, then try again.
Cause: An llm or config agent command in the REPL could not write the settings file. Usually the file or its folder is read-only, the file is open in another program, the drive is full, or the file is no longer valid JSON.
Fix: Do what the message says, then run the command again. Nothing needs to be undone first: the second line says what is still in place. A config agent setting is put back in the running session as well, so a refused change is not half-applied.
AskForge cannot tell where your home folder is, so it has nowhere to keep its settings and sessions. Set HOME to your home folder and run it again.
Cause: Ask Forge keeps askforge.json, the working context and your sessions in .schemasmith under your home folder, and no home folder could be named: HOME is not set, and the account has no home folder entry. This is common in a minimal container or under a service account. Ask Forge stops rather than putting those files in whatever folder it was started from. On Windows, the message names USERPROFILE instead of HOME.
Fix: Set HOME to a folder the account can write to, and run it again. The folder does not have to exist yet: Ask Forge creates .schemasmith under it.
Cause: The MCP server is not starting, or your client is not starting it.
Fix: Work through these in order:
ForgeBarrett.Mcp --version. It prints the version even without a license, so it confirms the executable runs.ForgeBarrett.Mcp on its own in a terminal. A license problem stops it at startup with one of the license errors above. If it starts, it waits for a client; press Ctrl+C to stop it.Unknown tool: schemasmith_manage_connection. Use discover_tools to find available tools.
Cause: The MCP server lists a curated set of tools, to keep token cost low. The rest are not missing: your assistant finds them with schemasmith_discover_tools and runs them with schemasmith_execute_tool. The message above is execute_tool's answer when tool_name matches no tool, as it does when the name keeps its prefix.
Fix: Pass the tool's name without the schemasmith_ prefix, as in manage_connection. Tool Visibility explains which tools are listed.
This operation requires confirmation.
Tool: schemasmith_execute_tool -> rename_table
Tier: Modify (Modifies files or creates packages)
Description: Rename a table with FK cascade and script scanning
To execute this tool, add 'confirm: true' to the execute_tool arguments alongside tool_name — not inside the inner 'arguments' JSON.
Cause: Over MCP, a Modify or External tool runs only when the call carries confirm: true, and a dry run is no exception. Nothing ran. The answer names the tool and its tier, and says where the flag goes.
Fix: Your assistant adds confirm: true to the call: in the arguments of a tool it calls directly, or alongside tool_name when it goes through execute_tool. Trust Levels explains the rule.
Tool 'execute_tool -> apply_change' requires higher trust level: tier Modify exceeds the Assistant trust level's maximum of Generate. Raising the trust level is the only way to permit it.
Cause: In the REPL, the conversational agent tried to run a tool above its trust level. At the default level, assistant, it cannot run Modify or External tools, whether it names one directly or reaches it through execute_tool.
Fix: Raise the trust level. A confirmation prompt is not an alternative. In the REPL:
config agent trustLevel operator
Trust Levels covers each level, and the setting in the settings file.
Error: Cannot show selection prompt since the current terminal isn't interactive.
Cause: A Modify or External subcommand needed your confirmation, and no prompt could be shown where it ran. It changed nothing and exited with code 1.
Fix: Pass --yes for that command, or set confirmationLevel in the agent section of the settings file. Direct Subcommands lists its values.
I can help with:
• `list-tables` - List tables in current template
Cause: On the command line, a word that is not a command is read as a question for Ask Forge. With no LLM provider set up, a question gets a built-in answer, usually this list of commands.
Fix: Commands use kebab-case: list-tables, not list_tables or listTables. ask-forge --help lists every command.
Could not find 'SchemaQuench' executable. Please ensure SchemaSmith tools are installed and available in PATH.
Or set the SchemaSmithPath environment variable to the install directory.
Cause: The Deploy tools run SchemaQuench, SchemaTongs, DataTongs and SchemaShears, which ship separately as SchemaSmith Community, and Ask Forge did not find the one the call needed. The message names it. Nothing ran. Ask Forge looks for each tool by name, in this order, and runs the first one it finds:
SchemaSmithPath environment variable, when it is set.C:\Program Files\SchemaSmith\SchemaSmith, then C:\Program Files\SchemaSmith. On macOS, /Applications/SchemaSmith/SchemaSmith.Fix: Install the SchemaSmith Community tools, or point SchemaSmithPath at the folder that holds them. Set it where Ask Forge runs: for the MCP server, in your client's configuration for the server.
$env:SchemaSmithPath = "C:\path\to\SchemaSmith"
export SchemaSmithPath="/path/to/SchemaSmith"
Direct CLI subcommands and MCP tool invocations work without any LLM provider; only the conversational question-answering mode requires one. The CLI shows the provider's status when the REPL starts, and before it answers a one-shot question.
LLM: Not configured - type 'llm setup' to configure
Cause: No provider is active, because none is set up yet. A question you ask gets a built-in answer, such as a list of commands, instead of one from a model.
Fix: Type llm setup in the REPL to run the setup wizard. LLM Providers covers each provider type.
LLM provider 'anthropic' has configuration issues: API key is required for Anthropic
LLM provider 'work' is set active but is not configured.
LLM provider 'work' could not be initialized: <reason>
Cause: The provider your settings file makes active cannot start. The first form lists what is missing: every provider needs a type and a model, and each type needs its own fields, such as an API key or an endpoint. An API key given as a ${ENV_VAR} reference counts as missing when the variable is not set where Ask Forge runs. The second form means the active value in the llm section names a provider that its providers list does not define. The third means the provider passed those checks but failed to start, and the reason says why. --quiet does not hide these messages.
Fix: Correct the provider in the settings file, or run llm setup again. LLM Providers lists the fields each type needs.
LLM: <provider> (<model>) ✗ Cannot connect to Ollama at <endpoint>: <reason>
Cause: The REPL tests the active provider when it starts, and the provider did not answer. For Ollama, the usual cause is a server that is not running, or one on a different address from the provider's endpoint.
Fix: Start Ollama (ollama serve) and check the endpoint in the provider's settings. For other types, check the endpoint and the API key. llm test runs the test again after you change something.
Couldn't reach the AI model: <reason>
Cause: The provider failed while answering a question. The reason is the provider's own.
Fix: Run llm test to check the connection, then ask again.
Sessions belong to the REPL. session save <name> saves the conversation, session load <name> or session load last loads one, and session list shows what is saved in the session directory. That is ~/.schemasmith/sessions unless the sessionDirectory setting names another.
Session '<name>' not found.
Cause: No saved session of that name is in the session directory in force. Name matching ignores letter case. session load last answers No saved sessions found. for the same reason.
Fix: session list shows the saved names. If you changed sessionDirectory, see the next item.
<count> earlier session file(s) remain in <old directory>. agent.sessionDirectory points ask-forge at <new directory>; nothing was moved. Copy them across, or point agent.sessionDirectory back at that directory, to see them here.
Cause: sessionDirectory changed. Changing it does not move the sessions you already have, and the new directory is the only one Ask Forge reads. session list and config tell you when earlier sessions are still somewhere you are no longer reading.
Fix: Copy the .json files, and the auto/ subfolder, into the new directory yourself, or point sessionDirectory back at the old one. It is read from the settings file only, so edit the file and restart the REPL.
Saved sessions store your side of the conversation as you typed it.
Cause: This is a notice, not an error. It appears when you turn on autoSaveSession, and when the REPL starts with it already on. session save prints a shorter form of it. Tool arguments with sensitive names, such as a password or an API key, are masked before they are written; your own words are not.
Fix: Keep credentials out of the conversation, and supply them as tool arguments or environment variables. To remove what is saved, use session delete <name> for a named session, or delete the auto/ subfolder of the session directory for the auto-saves. Turning autoSaveSession off stops new writes but leaves the existing files in place.
A license error exits with code 2, from the CLI and the MCP server alike. Console & Commands lists every CLI exit code and what it means.
Free schema-as-code for SQL Server, PostgreSQL, MySQL, and MariaDB.
The source is on GitHub for anyone to read.
Get Started on GitHub