Troubleshooting¶

Tip

1. Verify your credentials by logging in to the Qbee web UI at https://www.app.qbee.io
2. Check that environment variables are set correctly:

   echo $QBEE_USERNAME
   echo $QBEE_BASE_URL
   

3. If using provider block credentials, verify they match your Qbee account
4. Check that base_url matches your Qbee instance (default: https://www.app.qbee.io)
5. Prefer environment variables for credentials. If you need to test provider block configuration, do not commit credentials to version control; use variables instead of hardcoded values:

   provider "qbee" {
     username = var.qbee_username
     password = var.qbee_password
   }
   
   variable "qbee_username" {
     type = string
   }
   
   variable "qbee_password" {
     type      = string
     sensitive = true
   }
   

Tip

1. Verify the variables are exported (not just set):

   export QBEE_USERNAME="your-email@example.com"
   export QBEE_PASSWORD="your-password"
   

2. Verify they are visible to Terraform:

   env | grep QBEE
   

3. If using a CI/CD pipeline, ensure variables are set in the correct job context

Tip

1. Run terraform plan to see the full list of changes
2. For each unexpected change, determine if it was made manually
3. If the manual change should be kept, update your .tf files to match
4. If the manual change should be reverted, run terraform apply to restore your desired state

Tip

1. Read the error message carefully — it indicates which argument is invalid
2. Check the Resource Reference for the correct argument types and requirements
3. Ensure either tag or node is specified (not both, not neither) for resources that require targeting
4. Verify extend is set (it is required for most resources)
5. Run terraform validate for a quick syntax check:

   terraform validate
   

Tip

1. Check the error message for the HTTP status code:
   • 400 Bad Request — Invalid configuration values
   • 403 Forbidden — Insufficient permissions
   • 404 Not Found — Resource or tag/node does not exist
   • 429 Too Many Requests — Rate limit exceeded
   • 500 Internal Server Error — Qbee platform issue
2. For 400 errors, verify your configuration values match the expected format
3. For 403 errors, verify your Qbee account has the required permissions
4. For 404 errors, verify the tag or node ID exists in Qbee
5. For 429 errors, wait and retry (reduce parallelism with -parallelism=1)

Tip

1. Check your internet connectivity
2. Verify the Qbee API is accessible:

   curl -s -o /dev/null -w "%{http_code}" https://www.app.qbee.io
   

3. Check the Qbee status page for platform issues
4. If applying many resources, reduce parallelism:

   terraform apply -parallelism=1
   

Tip

1. Run terraform plan to see the current state — successfully applied resources show no changes
2. Fix the failing resource configuration based on the error message
3. Run terraform apply again — Terraform only applies the remaining changes
4. If stuck, use terraform state list to see managed resources and terraform state rm to remove problematic resources from state

Tip

1. Check for a backup state file (terraform.tfstate.backup)
2. If backup exists, restore it:

   cp terraform.tfstate.backup terraform.tfstate
   

3. If no backup and you are using a local backend, move the current state file aside instead of deleting it, then re-import resources:

   mv terraform.tfstate terraform.tfstate.corrupt
   terraform import qbee_parameters.example tag:production
   

4. If you are using a remote backend, do not delete or overwrite state directly. Check whether the backend supports versioning/snapshots or run terraform state pull > terraform.tfstate.backup to create a backup before restoring or re-importing resources

Tip

1. Wait for the other process to complete
2. If no other process is running, force-unlock:

   terraform force-unlock LOCK_ID
   

3. The LOCK_ID is shown in the error message
4. Only force-unlock when you are certain no other process is running

Tip

1. Run terraform refresh to update state from the actual Qbee configuration
2. If resources need re-importing:

   terraform import qbee_parameters.example tag:production
   

3. If state contains resources that were deleted manually, remove them from state:

   terraform state rm qbee_parameters.old_resource
   

Tip

1. Verify the configuration exists in the Qbee web UI
2. Check the import ID format — it must be tag:TAG_NAME or node:NODE_ID
3. Verify the tag name or node ID is spelled correctly (case-sensitive)
4. Example:

   terraform import qbee_parameters.example tag:production
   

Tip

1. Use the correct format: SCOPE:IDENTIFIER
2. For tag-targeted resources: tag:TAG_NAME
3. For node-targeted resources: node:NODE_ID
4. For non-targeted resources (filemanager, role, bootstrap_key, grouptree_group), use the resource-specific ID format — see Terraform Registry documentation

Tip

1. Run terraform plan to see all drift
2. Decide for each change:
   • Keep Terraform version: Run terraform apply to overwrite the manual change
   • Keep manual change: Update your .tf files to match, then run terraform plan to confirm no changes
3. To prevent future drift:
   • Restrict web UI access for Terraform-managed configurations
   • Run terraform plan on a schedule to detect drift early

Tip

1. Verify the parameter is defined in a qbee_parameters resource:

   resource "qbee_parameters" "config" {
     tag    = "production"
     extend = true
     parameters = [
       { key = "parameter-name", value = "actual-value" }
     ]
   }
   

2. Verify the parameter name matches exactly (case-sensitive)
3. Ensure the qbee_parameters resource has been applied before the resource that references it
4. Check that the parameter is defined for the same tag or an ancestor tag

Tip

1. Map out your parameter dependencies
2. Break the cycle by introducing a non-referencing intermediate parameter
3. Simplify parameter chains — avoid more than 2 levels of expansion

Tip

1. This is expected behavior for secrets_wo attributes
2. Use secrets_wo_version to control when secrets are rewritten:

   resource "qbee_parameters" "secrets" {
     tag                = "production"
     extend             = true
     secrets_wo_version = 1
     secrets_wo = [
       { key = "api_key", value = var.api_key }
     ]
   }
   

3. Only increment secrets_wo_version when you need to force a secret update

Tip

1. Increment secrets_wo_version and run terraform apply to force rewrite all secrets
2. Use Terraform as the sole source of truth for secrets
3. Restrict direct API/UI access to secret values

Tip

1. Test connectivity to the Qbee API:

   curl -v https://www.app.qbee.io
   

2. Check your firewall and proxy settings
3. Verify base_url is correct
4. Check the Qbee status page

Tip

1. Split large configurations into smaller state files (one per environment or module)
2. Use -target to plan specific resources:

   terraform plan -target=qbee_parameters.production
   

3. Use Terraform workspaces or separate directories for different environments