fix(deploy): actionable error when no target configured or no AWS creds (#604)

[aidandaly24]

Refs aws#604

Issues

• unhelpful error message on fresh project deployment summary aws/agentcore-cli#604 — On a freshly-created project, agentcore deploy --dry-run (the issue calls it --plan) with no AWS credentials configured fails with a developer-facing message — Target "default" not found in aws-targets.json — instead of telling the user that no deployment target is configured, that the likely cause is missing AWS credentials, and how to fix it. At filing time (Mar 2026) this hit every fresh project; at v0.20.2 it only hits the no-credentials edge case because deploy now auto-creates a default target when creds are detectable. Pure UX/error-message quality issue; functionality is intact.

Root cause

A fresh project writes an empty aws-targets.json (src/cli/commands/create/action.ts:96 writes []). handleDeploy calls ensureDefaultDeploymentTarget (src/cli/operations/deploy/actions.ts:156), which only auto-populates a 'default' target if detectAwsContext()/detectAccount() returns an accountId (ensure-target.ts:40-46). When no credentials are configured, detectAccount returns null (src/cli/aws/account.ts:58), so no target is written and the code falls through to the bare ResourceNotFoundError('Target "default" not found in aws-targets.json') at actions.ts:164. That ResourceNotFoundError is surfaced verbatim to the terminal (command.tsx:60 console.error(deployResult.error.message)). There is no credential validation gate before this point on a normal/plan deploy — validateAwsCredentials() runs only for teardown deploys (actions.ts:222). Note: expired/invalid creds are NOT affected — detectAccount throws AwsCredentialsError (account.ts:35-49) which propagates through the un-try/caught detectAwsContext call to handleDeploy's outer catch (actions.ts:923) and yields the good 'AWS credentials expired' message.

The fix

In handleDeploy, before the empty-target lookup, distinguish the no-credentials case from a genuinely-missing target. Simplest correct approach: have ensureDefaultDeploymentTarget (or handleDeploy) call validateAwsCredentials() when no targets exist and none could be auto-populated, so the no-creds case yields the existing actionable AwsCredentialsError message (account.ts:66-77 via getAwsLoginGuidance). Then reword the residual 'Target not found' ResourceNotFoundError (actions.ts:164) into an actionable message that says no deployment target is configured and lists the two remediations already documented in export/harness-action.ts:179-183: run agentcore deploy interactively to be prompted, or add a target to agentcore/aws-targets.json. Extract that guidance string into a shared constant so the deploy and export paths don't diverge. Small, self-contained in the CLI. Correction vs brief: do not claim the expired-creds case still shows the cryptic error — it is already handled.

Files touched: src/cli/commands/deploy/actions.ts:156-167 (ensureDefaultDeploymentTarget call + target-not-found return); add a no-creds guard reusing validateAwsCredentials/getAwsLoginGuidance from src/cli/aws/account.ts:66-77; reword using guidance text from src/cli/commands/export/harness-action.ts:179-183 (extract to a shared constant). Optionally surface the credentials guard inside src/cli/operations/deploy/ensure-target.ts.

Validation evidence

The fix was verified by reproducing the original symptom and re-running after the change:

Drove the real handleDeploy against a freshly-created project (real agentcore create --no-agent) with the AWS layer mocked at the single detectAccount seam (zero real AWS calls), comparing shipped HEAD vs fix/604.

BEFORE (shipped source): no-creds + empty aws-targets.json -> handleDeploy returns ResourceNotFoundError with message exactly Target "default" not found in aws-targets.json (the cryptic developer string from the symptom). Valid-creds + absent --target -> Target "does-not-exist" not found in aws-targets.json. Both assertions RED.

AFTER (fix/604): (1) No-creds case -> AwsCredentialsError, error.message = `No AWS credentials configured.

To fix this:

2. Or set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY..., error.shortMessage = No AWS credentials configured.; the literal not found in aws-targets.jsonno longer appears. (2) Missing-target (valid creds) -> ResourceNotFoundError(NO_DEPLOYMENT_TARGET_GUIDANCE) =No deployment target is configured in agentcore/aws-targets.json+ both documented remediations (runagentcore deployinteractively; or add a target to agentcore/aws-targets.json). (3) Regression guard: expired-creds still yields unchangedAWS credentials expired.` (green before and after).

Mechanism confirmed in src/cli/commands/deploy/actions.ts:190-204 — the if (!target) branch now calls await validateAwsCredentials() BEFORE returning, which throws AwsCredentialsError (account.ts:66-77) when detectAccount()

Test suite: green.

---

Staged on the fork as a draft for human review. Promote to aws/agentcore-cli after vetting.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	37.16%	13594 / 36579
🔵	Statements	36.43%	14453 / 39669
🔵	Functions	31.8%	2333 / 7336
🔵	Branches	31.1%	9000 / 28932

Generated in workflow #91 for commit 852926d by the Vitest Coverage Report Action