# SnapStart classpath error: Failed to load class from snapshot due to classpath mismatch

- **ID:** `aws/lambda-snapstart-classpath-error`
- **Domain:** aws
- **Category:** runtime_error
- **Verification:** ai_generated
- **Fix Rate:** 78%

## Root Cause

Lambda SnapStart snapshot was taken with a different classpath than the runtime environment, often caused by mutable classpath dependencies or environment variable changes after snapshot creation.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Lambda SnapStart (Java 11) | active | — | — |
| AWS SDK for Java 2.21.0 | active | — | — |

## Workarounds

1. **Ensure all dependencies are immutable and not downloaded at runtime. Use a layer or bundle all JARs in the deployment package:
# Example: build a fat JAR with Maven Shade Plugin
mvn clean package shade:shade
aws lambda update-function-code --function-name my-function --zip-file fileb://target/my-function.jar** (80% success)
   ```
   Ensure all dependencies are immutable and not downloaded at runtime. Use a layer or bundle all JARs in the deployment package:
# Example: build a fat JAR with Maven Shade Plugin
mvn clean package shade:shade
aws lambda update-function-code --function-name my-function --zip-file fileb://target/my-function.jar
   ```
2. **Set environment variables in the function configuration before taking the snapshot, and never change them after:
aws lambda update-function-configuration --function-name my-function --environment Variables={KEY=VALUE} --snap-start ApplyOn=PublishedVersions** (75% success)
   ```
   Set environment variables in the function configuration before taking the snapshot, and never change them after:
aws lambda update-function-configuration --function-name my-function --environment Variables={KEY=VALUE} --snap-start ApplyOn=PublishedVersions
   ```
3. **Publish a new version after fixing dependencies to take a fresh snapshot:
aws lambda publish-version --function-name my-function** (85% success)
   ```
   Publish a new version after fixing dependencies to take a fresh snapshot:
aws lambda publish-version --function-name my-function
   ```

## Dead Ends

- **Rebuild and redeploy the Lambda function without changing anything else** — The root cause is classpath mismatch; simply rebuilding without fixing the mutable dependency issue won't help. (90% fail)
- **Disable SnapStart and re-enable it** — Disabling and re-enabling SnapStart without addressing the classpath mismatch will reproduce the same error. (85% fail)
- **Increase Lambda memory or timeout** — Classpath errors are not related to memory or timeout; these settings don't affect class loading. (95% fail)