Skip to main content

Migration Troubleshooting

This page covers common issues encountered during NTC module migrations and their solutions.

Module-Specific Issues

For version-specific migration issues, refer to the individual module migration guides (e.g., v1→v2 NTC Organizations).

Provider Issues​

Error: Unsupported AWS Provider Version​

Symptom:

Error: Unsupported Terraform Core version
This configuration does not support Terraform version X.X.X

Solution: Update your Terraform CLI to minimum requirements:

# Check current version
terraform version

# Update via package manager (example for macOS)
brew upgrade terraform

# Or download from terraform.io

Error: Provider Configuration Not Present​

Symptom:

Error: Provider configuration not present
provider "registry.terraform.io/hashicorp/aws"

Solution: Run terraform init -upgrade to fetch the new provider version:

terraform init -upgrade

Error: Invalid Provider Configuration​

Symptom:

Error: Unsupported argument
on main.tf line X: region attribute is not expected

Solution: This occurs when using v2 module configuration with AWS Provider v5. Ensure you've updated to provider v6:

required_providers {
  aws = {
    source  = "hashicorp/aws"
    version = "~> 6.0"  # Must be v6
  }
}

State Migration Issues​

Resources Being Recreated Instead of Moved​

Symptom:

terraform plan shows:
  # module.ntc_organizations... will be destroyed
  # module.ntc_organizations... will be created

Solution:

  1. Verify state addresses - List current resources:

    terraform state list | grep ntc_delegated_admins

  2. Check moved block accuracy - Ensure from address matches exactly:

    # If your state shows:
    # module.ntc_delegated_admins_euc1.aws_organizations_delegated_administrator.admin["config.amazonaws.com"]

    # Your moved block should be:
    moved {
      from = module.ntc_delegated_admins_euc1.aws_organizations_delegated_administrator.admin["config.amazonaws.com"]
      to   = module.ntc_organizations.module.admin_delegations.aws_organizations_delegated_administrator.ntc_delegated_admin["config.amazonaws.com"]
    }

  3. Apply in stages - Comment out unrelated moved blocks and migrate incrementally

Error: Moved Block Conflicts​

Symptom:

Error: Moved object to conflicting destination

Solution: Two moved blocks may target the same destination. Check for duplicates:

grep -n "to =" state_migrations.tf | sort -k2

Remove or correct duplicate moved blocks.

Error: Resource Not Found in State​

Symptom:

Error: Invalid move operation
The source object does not exist in current state

Solution:

This means the from address doesn't exist. Possible causes:

  1. Already migrated - Resource may have been migrated in a previous run
  2. Typo in address - Verify with terraform state list
  3. Resource never existed - Remove the moved block
# Check if resource exists
terraform state show 'module.ntc_delegated_admins_euc1.aws_organizations_delegated_administrator.ntc_delegated_admin["config.amazonaws.com"]'

Configuration Issues​

Missing Required Argument​

Symptom:

Error: Missing required argument
The argument "X" is required, but no definition was found.

Solution: Check the module documentation for the target version to identify new required arguments. Add the missing argument to your configuration:

module "example" {
  source = "github.com/nuvibit-terraform-collection/terraform-aws-ntc-module?ref=X.X.X"
  
  new_required_argument = "value"  # Add missing argument
  
  # ... rest of configuration
}

Invalid Variable Type or Structure​

Symptom:

Error: Invalid value for "variable_name" variable

Solution: Variable structures may change between versions. Review the migration guide for the specific module to understand the new structure. Common patterns:

  • Flat list → nested map
  • String → object with multiple attributes
  • Single value → list of values

Check the module's migration documentation for before/after examples.

Provider Alias Configuration Errors​

Symptom:

Error: provider.aws.alias: no suitable version installed

Solution: Ensure all required provider aliases are configured:

provider "aws" {
  alias  = "alias_name"
  region = "region-name"
}

Review the module documentation to understand which provider aliases are required.

AWS Sovereign Cloud Issues​

Region Not Available in Sovereign Cloud​

Symptom:

Error: Invalid AWS Region
The specified region is not available in this partition

Solution:

AWS European Sovereign Cloud has different region codes:

Commercial RegionESC Region
eu-central-1Not available (use eusc-de-east-1)
us-east-1Not available

Update your region configuration for ESC:

region = "eusc-de-east-1"  # ESC region

Service Not Available in Sovereign Cloud​

Symptom:

Error: Service X is not available in this region

Solution:

Some AWS services aren't available in sovereign clouds. Check service availability:

  1. Review AWS documentation for service availability in your partition
  2. disable unsupported features
locals {
  is_sovereign_cloud = data.aws_partition.current.partition != "aws"
}

module "ntc_organizations" {
  source = "..."
  
  # NOTE: service quota templates are currently not supported in the ESC
  service_quota_templates = []
}

Performance Issues​

Terraform Plan Takes Very Long​

Symptom: Plan operation takes 5+ minutes

Solution:

  1. Use targeted plans during migration:

    terraform plan -target=module.ntc_organizations

  2. Break migration into steps:

    • First migrate state (with moved blocks)
    • Then update configuration
    • Finally clean up

  3. Reduce parallelism if API throttling occurs:

    terraform plan -parallelism=5

API Rate Limiting​

Symptom:

Error: ThrottlingException: Rate exceeded

Solution:

AWS Organizations API has rate limits. Options:

  1. Retry with exponential backoff (automatic in most cases)
  2. Reduce parallelism: 
    terraform apply -parallelism=3
  3. Request limit increase from AWS Support (if frequent issue)

Validation Issues​

Resources Exist But Not in Expected State​

Symptom: After migration, resources look different in AWS Console

Solution:

  1. Check resource attributes:

    terraform state show 'module.ntc_organizations.aws_organizations_organization.ntc_org'

  2. Refresh state:

    terraform refresh
    terraform plan

  3. Compare with AWS Console to identify drift

Rollback Procedures​

Rolling Back a Failed Migration​

If migration fails and you need to rollback:

  1. Restore Terraform state backup:

    # Local state
    cp terraform.tfstate.backup terraform.tfstate

    # S3 state
    aws s3 cp ./terraform.tfstate.backup s3://your-bucket/path/to/terraform.tfstate

  2. Revert configuration changes:

    git revert <migration-commit-sha>

  3. Revert provider version (if changed):

    required_providers {
      aws = {
        source  = "hashicorp/aws"
        version = "~> 5.0"  # Revert to previous version
      }
    }

  4. Re-initialize:

    terraform init -upgrade
    terraform plan  # Should show no changes

Getting More Help​

If you're still stuck:

1. Enable Debug Logging​

export TF_LOG=DEBUG
export TF_LOG_PATH=./terraform-debug.log
terraform plan

Review the log for detailed error information.

2. Contact Support​

Provide this information when contacting support:

  • Module name and versions (e.g., v1.x → v2.x)
  • Terraform version (terraform version)
  • Provider versions (e.g., AWS Provider version)
  • Redacted error messages
  • Relevant configuration snippets
  • Debug logs (if applicable)