Use the failing task and its reported endpoint or runtime directory to narrow the problem. Development lifecycle tasks and managed test tasks operate on separate instances.

The Plugin Cannot Be Resolved

Check the plugin ID and requested version against the Gradle Plugin Portal listing for the core plugin or Spring Boot companion. Include a version in the plugins declaration unless it is supplied by plugin management or the build classpath.

Gradle searches the Portal by default. If your settings customize pluginManagement.repositories, include gradlePluginPortal() there; adding it only to the project’s dependency repositories does not configure plugin resolution. Check network or proxy access to the Portal, and avoid --offline when the plugin has not been cached.

Check that Java is at least 17 and Gradle is at least 8.14. See Plugin Portal setup. When testing local plugin changes, follow the checkout setup and omit the emulator plugin version.

Docker Is Unavailable Or Startup Times Out

Confirm the selected Docker engine is running Linux containers and that the configured dockerExecutable is available in the Gradle runner. The first run needs network access to build or pull the image. For containerized runners and remote engines, select DockerTransport.TUNNEL; see CI and remote Docker.

Run ./gradlew doctorAwsEmulator for a read-only report of the configured Docker executable, daemon, platform, image availability, port, project-owned containers, generated connection files, and HTTPS health. It reports diagnostic errors without starting an emulator or building/pulling an image. Missing connection files and changed settings are identified in the report.

For a development instance:

./gradlew statusAwsEmulator
./gradlew logsAwsEmulator

Use buildTimeoutSeconds for slow image builds or pulls, commandTimeoutSeconds for normal Docker commands, and startupTimeoutSeconds for HTTPS readiness after startup. Increasing one does not change the others.

These status/log tasks inspect the development instance. For managed failures, inspect the failed task’s output and the printed archive path under .aws-emulator/logs/ (or the owner’s custom workingDirectory/logs/). Complete available timestamped logs are saved before managed teardown, including ordinary task failures and failed startups that created a container. Archive failure prints a warning and does not prevent cleanup. Logs survive cleanup until explicitly deleted.

A Port Is Already In Use

The plugin selects an available port by default. If you configured a fixed port, remove that setting to restore automatic selection for concurrent projects, builds, or a managed instance alongside a persistent development instance.

With DIRECT, automatic selection has a short race before Docker binds the port. If another process claims it, startup fails and cleans up. Retry after resolving the competing process. TUNNEL reserves its local listener atomically and publishes no emulator port on the engine.

An explicit port.set(…​) takes precedence over -PawsEmulator.port=…​. Leave the build-script port unset to retain the command-line override and automatic fallback; see configuration.

Development Settings Changed

startAwsEmulator only reuses an instance whose settings match. Use restartAwsEmulator to apply changed settings. Restarting discards the emulator’s in-memory AWS resources.

A Test Ran Without Prepared Resources

Check both pieces of wiring:

  1. The test provider is passed to awsEmulator.useWith(…​).

  2. The required provisioning tasks or resource sets are passed as setup arguments to that call.

Keep provisioning tasks in the default MANAGED mode to share the test runtime. A DEVELOPMENT task creates resources in a separate instance. A standalone managed provisioning build removes its resources at the end; run setup and consumers in the same build.

Pass provisioning tasks or their wrapper task as setup arguments to useWith, for example useWith(tests, EmulatorMode.MANAGED, createQueue). The plugin checks those tasks and their local prerequisites before execution. An error such as setup task :createQueue uses DEVELOPMENT but consumer :test uses MANAGED means the setup and consumer would use separate instances. Set matching modes, or use a reusable resource set to create independent managed and development task graphs.

Tests that are skipped or have no sources do not start the emulator themselves, but their provisioning dependencies can still execute.

SQS Attributes Conflict

An existing queue is reused only when explicitly requested attributes match the returned strings. The task fails instead of updating or purging a queue on mismatch. Check the requested values, including the formatting of JSON-valued attributes.

For FIFO queues, use both a .fifo suffix and the FifoQueue attribute set to the string true. Use distinct queue names when concurrent tests share an instance.

HTTPS Or Authentication Fails

Use a compatible SDK and its normal endpoint and credential providers. Explicit client settings can override the plugin. For host-prefix operations in Java, configure SdkAdvancedClientOption.DISABLE_HOST_PREFIX_INJECTION.

The plugin merges the selected JVM’s default roots, any configured custom trust store, and the emulator certificate. For a private HTTPS service, configure its CA in the consuming task’s custom trust store. If trust preparation fails, check the source path (relative to the task’s working directory), type, provider, and password. See credentials and TLS. Check that host clients use host-config, not the emulator’s config with container paths.

A Container Remains After Interruption

Ordinary task failures trigger managed cleanup. A hard kill or unavailable Docker daemon can prevent it. Preview and remove stale managed containers owned by the selected runtime project:

./gradlew cleanupAwsEmulator --report-only
./gradlew cleanupAwsEmulator

Cleanup archives logs before removal and verifies ownership labels, the runtime-home marker, and the managed lifetime lock. It skips instances still leased by an active build and all development instances. Legacy running containers without a lifetime lock are skipped because activity cannot be established; identify and stop those individually before retrying. A running development instance intentionally survives Gradle; use stopAwsEmulator when that session is finished.

For TUNNEL, cleanup skips running containers because another runner’s filesystem cannot prove that its build has ended. It can remove stopped, owned tunneled containers even when their original runner directory is unavailable. See remote cleanup and diagnostics.

A Shell Or IDE Uses An Old Connection

Run exportAwsEmulatorConnection again, source the printed POSIX or PowerShell script, and launch a fresh application/IDE process. Restart changes generated credentials and may change the port. An existing IDE process does not automatically inherit later shell changes. Remove explicit SDK endpoints, credential settings, and per-service environment overrides from its run configuration. See shell and IDE exports.