hcpt-troubleshooting

name	hcpt-troubleshooting
description	Debug HCP Terraform run failures using hcpt CLI. Use when a Terraform run fails, a PR check is red, or you need to investigate workspace errors.

HCP Terraform Troubleshooting

This skill guides you through debugging failed HCP Terraform runs using the hcpt CLI tool.

Prerequisites

• hcpt CLI installed and configured with a valid HCP Terraform token
• Organization name configured (hcpt config set org <org-name>)

Debugging Workflow

Step 1: Identify the Failed Run

If you have a GitHub PR with a failed Terraform check:

hcpt run show --repo <owner/repo> --pr <number>

If multiple workspaces are linked, specify which one:

hcpt run show --repo <owner/repo> --pr <number> --workspace <name>

If you already know the run ID:

hcpt run show --org <org> --run <run-id>

Step 2: Check Error Logs

Extract only the error lines from the apply/plan logs:

hcpt run logs --org <org> --run <run-id> --error-only

For full logs:

hcpt run logs --org <org> --run <run-id>

Step 3: Review Workspace Configuration

Check workspace settings for misconfiguration:

hcpt workspace show --org <org> --workspace <name>

Step 4: Check Variables

List workspace variables to verify values:

hcpt variable list --org <org> --workspace <name>

Update a variable if needed:

hcpt variable set --org <org> --workspace <name> --key <key> --value <value>

Step 5: Review Run History

Check recent runs to identify patterns:

hcpt run list --org <org> --workspace <name>

Filter by status to find all failed runs:

hcpt run list --org <org> --workspace <name> --status errored

Common Failure Patterns

• Authentication errors: Check TFE_TOKEN or cloud provider credentials in variables
• State lock: Another run may be in progress; check run list for active runs
• Provider version mismatch: Review workspace Terraform version setting
• Missing variables: Compare required variables with hcpt variable list output

Tips

• Use --json flag on any command for machine-readable output
• Use hcpt run show --watch to monitor a running plan/apply until completion
• Use hcpt config list to verify your current configuration