MCP Server Troubleshooting

Azure scans fail: missing subscription / ARM_SUBSCRIPTION_ID

Symptom: Azure tool calls fail to resolve a subscription, even though az login works fine in your normal shell.

Cause: MCP clients spawn the terraback mcp server process with a limited environment by default — it does not inherit your full interactive shell environment or az login context the way a terminal session does. azurerm 4.x providers in particular may need the subscription ID set explicitly rather than resolved implicitly.

Fix: add ARM_SUBSCRIPTION_ID to the server's env block in .mcp.json:

{
  "mcpServers": {
    "terraback": {
      "type": "stdio",
      "command": "terraback",
      "args": ["mcp"],
      "env": {
        "ARM_SUBSCRIPTION_ID": "<your-subscription-id>"
      }
    }
  }
}

Restart the MCP client (or reload the server) after editing .mcp.json for the environment change to take effect.

terraform not found, or version < 1.5

Symptom: verify_plan fails immediately, or reports it cannot find terraform.

Cause: verify_plan shells out to terraform init and terraform plan in the directory you point it at. It needs terraform on the PATH of the MCP server process, and import blocks — which the generated code relies on — require Terraform 1.5 or newer.

Fix:

Confirm the version available to the server process, not just your shell:
```
terraform version
```
Install or upgrade to Terraform 1.5+ if it is missing or older.
If Terraform is installed but not on the MCP server's PATH (common when the client spawns the server with a limited environment — see the Azure note above), add the directory containing the terraform binary to the server's env PATH entry in .mcp.json, or point at it with an absolute path if your setup requires it.

Large inventories: reading the inventory_file

Symptom: scan_infrastructure or detect_unmanaged returns a summary with summary.total well over 200, but the resource list in the response looks empty or truncated.

Cause: to keep tool responses small, the full resource list is inlined only up to 200 entries. Larger inventories (over 200 resources) are instead written to an inventory_file on disk, and the response is summarized (summary.total, summary.counts_by_type) rather than fully inlined.

Fix: read inventory_file from the tool result and load that JSON file directly to see individual resources. Prefer narrowing the scan with types or tag_filters in the first place when you only need a subset — it avoids the large-inventory path entirely and is faster.

detect_unmanaged with a remote Terraform backend

Symptom: detect_unmanaged (or codify_batch with exclude_managed: true) does not seem to see resources you know are already managed, even though you have a remote backend (S3, azurerm, GCS, Terraform Cloud/Enterprise) configured.

Cause: in v1, state_files accepts local Terraform state JSON file paths only. Remote backends are not read directly.

Fix: pull the remote state to a local file first, then pass that path:

terraform state pull > state.json

{
  "provider": "aws",
  "scope": "us-east-1",
  "state_files": ["./state.json"]
}

stdio discipline: where did my log output go?

Symptom: you expected to see Terraback's normal progress output (scanner start/ finish messages, resource counts) but the MCP client shows nothing, or the connection appears to hang with no visible activity.

Cause: MCP's stdio transport requires stdout to carry only the JSON-RPC protocol stream. Terraback's scanning code normally prints a lot of human-readable progress via the CLI's console output; under terraback mcp, all of that is redirected to stderr instead so it cannot corrupt the protocol stream on stdout. This is expected behavior, not a hang — the tool call is still progressing.

Fix: if you need to see that diagnostic output while debugging the server, run it directly with stderr captured to a file, and tail the file separately:

terraback mcp 2>server.log

tail -f server.log

Do not expect diagnostic output on stdout — by design, only the protocol stream belongs there.

Still stuck?

Confirm the tools are visible to your client at all: terraback --help should list an mcp command, and your MCP client's tool list should show the six tools documented in the Tool Reference.
Re-check the read-only role assignments in Security and Credentials — a scoped-down role missing a permission looks the same as a scan returning zero resources.
For issues in the underlying scan/codify/import engine that are not specific to the MCP transport, see the general Troubleshooting Guide.
Email: contact@terraback.io — report bugs and request features.

Azure scans fail: missing subscription / ARM_SUBSCRIPTION_ID​

terraform not found, or version < 1.5​

Large inventories: reading the inventory_file​

detect_unmanaged with a remote Terraform backend​

stdio discipline: where did my log output go?​

Still stuck?​