Skip to content

troubleshooting.md

Latest commit

 

History

History
103 lines (62 loc) · 3.88 KB

troubleshooting.md

File metadata and controls

103 lines (62 loc) · 3.88 KB
Raw

Troubleshooting

Common issues and how to resolve them. If your problem isn't listed here, check SUPPORT.md for where to ask.

Installation & Build

go: module github.com/skyoo2003/devcloud: Go 1.26 required

Upgrade Go to 1.26 or later. Check with go version. See go.dev/dl.

Running the Server

bind: address already in use on port 4747

Another process is already on port 4747. Either stop it or change DevCloud's port:

# devcloud.yaml
server:
  port: 4100

Or for Docker, map to a different host port:

docker run -p 4100:4747 ghcr.io/skyoo2003/devcloud:latest

Server starts but clients get connection refused

Check that the server is actually listening:

curl http://localhost:4747/devcloud/api/health

If that fails:

  • On Docker for Mac/Windows, make sure you used -p 4747:4747 (not just -p 4747)
  • If you're inside another container, localhost refers to that container. Use the host bridge (e.g., host.docker.internal on Docker Desktop) or a shared Docker network.

Permission denied on ./data/

The Docker container may write as root while your host user owns the mount. Either run the container with your UID:

docker run --user $(id -u):$(id -g) -p 4747:4747 -v $(pwd)/data:/app/data ghcr.io/skyoo2003/devcloud:latest

Or pre-create the data directory with permissive mode (chmod 777 data) if you're OK with that for local development.

SDK / Client Errors

SignatureDoesNotMatch or signature-related errors

By default, DevCloud accepts any signature — it checks the SigV4 format but does not verify the secret. If you see signature errors, make sure:

  • Your client is configured with dummy but non-empty credentials (aws_access_key_id="test", aws_secret_access_key="test").
  • The endpoint_url points to DevCloud, not real AWS.

NoSuchBucket / ResourceNotFoundException after restart

Check whether the service has a persistent backend (see configuration.md). SQS is in-memory and loses state; S3 / DynamoDB / Lambda / IAM persist only if data_dir points to a mounted volume (when using Docker).

Operation X is not implemented errors

Not every operation of every service is implemented. Check services-matrix.md for the current coverage, and file a Feature Request if the operation you need is missing.

Terraform apply succeeds but terraform plan shows drift next time

Some services return default values that real AWS does not echo back, and vice versa. This is a known compatibility gap. Workarounds:

  • Use ignore_changes on the specific attributes
  • Pin DevCloud and Terraform AWS-provider versions together
  • File a bug with the exact resource and attributes involved

Lambda

Lambda function returns runtime not available

DevCloud's Lambda implementation is a stub — it accepts function registration but does not execute your handler code locally. Real function execution requires configuring services.lambda.runtime. This is an area under active development; see roadmap.md.

Lambda invocations hang

Ensure Docker is running if you have configured Lambda to use a Docker-based runtime. Check DevCloud's logs for container startup errors.

Admin API

GET /devcloud/api/* returns 404

The admin API is disabled by default. Enable it:

# devcloud.yaml
admin:
  enabled: true

Then restart the server. The web dashboard UI is a separate project (its own repository); this server only exposes the admin API, not a bundled UI.

When to open an issue

If your problem isn't listed here and you have checked SUPPORT.md, open a bug report with the reproduction template filled in.