Skip to main content

Troubleshooting

This page covers common issues encountered when deploying and running enclaves with Oyster CVM and Serverless.

Minimum Duration for Deployments​

Issue: Deployment fails or enclave doesn't have enough time to initialize.

Solution: Set deployment duration to at least 15 minutes. While the technical minimum is 5 minutes, enclave setup takes several minutes, so shorter durations may not leave enough time for interaction.

oyster-cvm deploy --duration-in-minutes 15 ...

Failed to Parse IP Endpoint Response (400 Bad Request)​

Issue: oyster-cvm simulate passes but oyster-cvm deploy fails with:

Failed to parse IP endpoint response (status: 400 Bad Request)

Cause: This error occurs when the CP cannot return an IP address. Common reasons include:

  • Architecture mismatch between instance type and enclave image
  • Enclave image not available
  • Enclave deployment failure

Example of mismatch:

instance: c6g.xlarge (ARM-based)
url: https://artifacts.marlin.org/oyster/eifs/base-blue_v3.0.0_linux_amd64.eif (AMD64)

Solution:

  • For AMD64 images, use Intel-based instances like the c6i family (e.g., c6i.xlarge)
  • For ARM images, use ARM-based instances like the c6g family
  • Ensure docker image architecture matches enclave architecture

Invalid Init Param Enclave Path​

Issue: Error when running simulate with init params:

Failed to compute individual digest: Invalid init param enclave path: /app/.env

Cause: The enclave path in init params must point to the /init-params/ directory inside the enclave.

Solution: Update your docker-compose file to reference the correct path:

# Incorrect
env_file:
  - .env

# Correct
env_file:
  - /init-params/.env

Encrypted Init Params in Debug Mode​

Issue: Deployment fails with error when using encrypted init params with --debug flag:

Refused to allow encrypted init params in debug mode enclaves. It is not safe to use encrypted init params in debug mode since it can then be decrypted and exported by other debug enclaves.

Cause: Debug mode enclaves have relaxed security constraints. Encrypted init params could be decrypted and extracted by other debug enclaves, creating a security vulnerability.

Solution: Debug mode is intended for testing and development only. When using debug mode:

  1. Use dummy/test secrets - Never use real credentials or sensitive data in debug mode
  2. Assume all data is public - Treat any init params provided in debug mode as potentially leaked
  3. Set encrypt flag to 0 - Since you're using test data anyway, disable encryption:
# Use dummy secrets with encrypt flag set to 0
oyster-cvm deploy --debug --init-params secret:1:0:utf8:test-dummy-value ...
warning

Only use production secrets with non-debug deployments where encryption is properly enforced.

Same Image ID for Different Docker Images​

Issue: Different docker images result in the same image ID, causing shared KMS keys.

Cause: The image ID is computed from the docker-compose file content and init params, not the actual docker image contents. If you use tags like latest or v1.0 without a digest hash, updating the image won't change the image ID.

Security Implications: If an upstream image provider pushes a malicious update to the same tag, it could potentially access your KMS keys.

Solution 1: Pin docker images using their digest hash:

# Less secure - tag can be updated
image: myapp:v1.0

# More secure - pinned to specific image
image: myapp@sha256:abcd1234...
tip

Use reproducible docker builds and specify the image hash in the tag to ensure the verified and expected docker image is deployed.

Solution 2: Use Contract KMS if you need to maintain the same keys across different image versions. Contract KMS allows you to explicitly approve which image IDs can derive the same keys, giving you control over key continuity during application updates while preventing unauthorized access.

Verifying Image ID​

Issue: Computed image ID doesn't match the deployed image ID.

Solution: Machine architecture and init params affect the image ID.

To verify:

  1. Use oyster-cvm compute-image-id to calculate the expected image ID
  2. The calculated image ID should always match with the image ID logged during deployment (oyster-cvm deploy)
  3. Ensure docker image architecture matches enclave architecture (e.g., AMD64 image with Intel instance)

Contract KMS and Debug Mode​

Issue: Contract KMS doesn't work with debug mode.

Cause: In debug mode, PCRs (Platform Configuration Registers) are always set to 0. The contract-based KMS system doesn't provide keys to enclaves running in debug mode.

Solution: Use production mode when deploying with contract KMS. For local testing, use simulate mode with Mock KMS instead.

Contract KMS in Simulate Mode​

Issue: Contract KMS is not available in simulate mode.

Solution: Simulate mode supports Mock KMS derive server-based derivation at endpoint 127.0.0.1:1100 only.

important

Mock KMS derive server is provided in oyster-cvm simulate for testing Contract KMS workflows, but you can't expect the same key every time like in production Contract KMS.