Overcast is alpha — behaviour and APIs may change between releases. Pin your version and read the changelog before upgrading.

overcast

CDK troubleshooting

Symptom, cause and fix for a CDK deploy against Overcast: a bootstrap that fails, a stack that never leaves CREATE_IN_PROGRESS, and the Windows S3 asset upload.

When cdk bootstrap or cdk deploy misbehaves against Overcast, start here; Using AWS CDK has the working setup every entry assumes.

SymptomCauseFix
cdk bootstrap failsOvercast is not running, or AWS_ENDPOINT_URL is unsetStart Overcast and export the endpoint. Bootstrap needs S3, SSM, IAM and STS, all supported
A stack sits in CREATE_IN_PROGRESSProvisioning runs on a background goroutine, so this is expected brieflyWait. If it never clears, a resource handler is hung or failing — check the server logs
A stack ends in ROLLBACK_COMPLETEA resource handler failedThe server logs name it
Fn::GetAtt returns an unexpected valueThe attribute is not one of the supported onesUnsupported attributes fall back to the resource’s physical ID — see the CloudFormation reference
A --hotswap deploy behaves differently from a full oneHotswap bypasses CloudFormation and calls the service API directly, such as UpdateFunctionCodeIt works wherever that operation is implemented — check the service’s page
Some resources have no backing stateTheir types are stubbedResource type coverage, then Partial resource coverage
cdk deploy fails on Windows with an S3 connection or DNS error*.localhost subdomains do not resolve on WindowsBelow

S3 asset upload fails on Windows

Symptom: cdk deploy fails on Windows with an S3 connection or DNS resolution error after a successful bootstrap. The error originates in the CDK asset publisher (Node.js), not in the CloudFormation create/update step.

Root cause: CDK’s asset publisher sends S3 requests using virtual-hosted style, constructing a bucket hostname from your endpoint URL:

cdk-hnb659fds-assets-<account>-<region>.localhost

On Windows, *.localhost subdomains do not resolve by default — only localhost itself is in the hosts file. On Linux and macOS the system resolver handles *.localhost automatically, so this issue does not affect those platforms.

Fix: Use a wildcard-DNS hostname instead of localhost. Overcast treats the OVERCAST_HOSTNAME environment variable as an additional virtual-host base, so any <bucket>.<hostname> request is correctly rewritten to path-style.

Every *.localhost.overcast.sh subdomain resolves to 127.0.0.1 on every OS, with no hosts-file edits — see Hostnames that resolve for every caller:

# Start Overcast with the wildcard-DNS hostname
docker run --rm -p 4566:4566 \
  -e OVERCAST_HOSTNAME=localhost.overcast.sh \
  ghcr.io/overcast-sh/overcast:latest

# Point CDK at that hostname
export AWS_ENDPOINT_URL=http://localhost.overcast.sh:4566
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_DEFAULT_REGION=us-east-1

npx cdk bootstrap aws://000000000000/us-east-1
npx cdk deploy --require-approval never

CDK then constructs a bucket hostname like cdk-hnb659fds-assets-000000000000-us-east-1.localhost.overcast.sh:4566, which Overcast’s S3 virtual-host middleware rewrites to the path-style route.

Note

The same hostname works on Linux and macOS, so it is safe in a shared CI/CD environment where developers are on different host operating systems. It needs a public DNS lookup, so it does not work offline or behind DNS rebinding protection — Hostnames that resolve for every caller has the fallbacks, and the other two wildcard domains Overcast recognises.