SSM ParameterNotFound: Every Reason the Name Fails

AWS Systems Manager Parameter Store returns ParameterNotFound when a GetParameter request cannot resolve the specified parameter in the request’s account and Region. The first fix is to compare the complete, case-sensitive name, then the CLI profile and Region; a hierarchical name must include its leading slash. Here is the counterintuitive detail: GetParameters can report a missing name in InvalidParameters while the API call itself succeeds, so code that only catches exceptions can miss the failure. A path lookup, encryption permissions, and version selectors require separate checks.

Jake runs a phone shop that uses a Lambda function to look up a public service URL and an encrypted payment credential. One morning, the configuration lookup fails, although Jake can still see the parameter in the Systems Manager console. His online booking workflow cannot start, even though the parameter seems to be right where he left it.

He is comparing the console in one Region with a terminal configured for another. That is an easy mistake because the same console session can switch Regions, while an AWS CLI profile keeps its own settings. The failure feels like a lost file, but the first investigation is about the address used to request it.

Jake: "The console shows the value. Is Parameter Store hiding it from the function?"

Ethan: "Most of the time, the function is asking the wrong account, Region, or exact name. Check those three before changing any policy."

Read ParameterNotFound before changing your code

If you see ParameterNotFound after calling GetParameter, the service could not find the named parameter for that request. This error is distinct from a response that contains an empty value. It also differs from AccessDeniedException, which indicates that an authorization check blocked your action.

You should record the name passed by the application, the AWS Region, and the identity that made the request. These are the three coordinates needed to look up the same resource. You can then compare them with the parameter detail page in the console instead of repeatedly guessing names.

Parameter Store has String, StringList, and SecureString parameter types. All three are read through the SSM API, but a SecureString retrieval may also require KMS decryption permissions. A missing parameter and an undecryptable parameter are different investigations.

If your error comes from Lambda, ECS, CloudFormation, or a custom application, first identify which underlying API was used. An SDK GetParameter call is not interchangeable with an ECS startup secret injection or CloudFormation dynamic reference. The outer service may wrap or replace the underlying error message.

aws ssm get-parameter --name /shop/prod/payment-url --region us-east-1
# Typical CLI error when absent:
# An error occurred (ParameterNotFound) when calling the GetParameter operation:

Check every Parameter Store naming rule

When a name looks right but still fails, treat the spelling as exact data rather than a convenient label. Parameter names are case-sensitive, so /Shop/Prod/Db and /shop/prod/db are different names. Copy the complete Name field from the console instead of retyping a guessed casing.

Hierarchical names require a leading slash, as in /shop/prod/db. A root-level name may be MyParameter or /MyParameter; for a hierarchical name, shop/prod/db without the initial slash is not fully qualified. The hierarchy supports up to 15 levels.

Names allow letters, digits, underscores, periods, hyphens, and slash delimiters, but no spaces inside a name. Parameter names cannot begin with the reserved prefixes aws or ssm, case-insensitively; that restriction also applies to hierarchical names such as /aws/.... Creating a prohibited name produces validation trouble rather than a successful parameter that later vanishes.

Parameter names have a practical maximum of 1,011 characters including the ARN prefix that comes before the name. API models may display a 2,048-character field because part of that allowance is reserved internally. The Region and account digits affect the number of characters consumed by the ARN prefix.

Fix the Region mismatch when console and CLI disagree

If the parameter appears in the console but not from your terminal, look at the Region selector in the upper-right corner of the AWS console. Parameter Store is regional, and the CLI chooses a Region from command flags, profiles, or environment variables. A parameter in us-east-1 is not automatically duplicated into us-west-2.

Run aws configure list to discover which configuration is providing the active Region. Then add an explicit --region to a read command so the test is unambiguous. This is especially valuable when a CI job or local shell sets AWS_REGION or AWS_DEFAULT_REGION.

Use describe-parameters to search names in the target Region without displaying their decrypted values. The response may be paginated, so allow the AWS CLI paginator to continue rather than assuming the first page is exhaustive. If the parameter appears, copy its Name field into get-parameter.

Keep your production configuration explicit about Region. A Lambda function in one Region normally creates an SDK client for that Region unless its code overrides it. If you intend to read a different Region, specify that behavior intentionally and review the network and IAM implications.

aws configure list
aws ssm describe-parameters --region us-east-1 --query "Parameters[].Name"
aws ssm get-parameter --name /shop/prod/payment-url --region us-east-1

Confirm the AWS account and assumed role

Your terminal can have a valid AWS login and still be connected to the wrong account. This is common when developers switch between development and production profiles. The same parameter name can exist separately in multiple accounts, and its presence in one account does not make it visible in another.

Run aws sts get-caller-identity using the same profile as the failed request. The response identifies the account and principal actually making AWS API requests. Compare the Account value with the account that owns the parameter rather than the account you expected to use.

For an assumed role, the returned ARN identifies a role session. Check the role trust and the role permissions instead of only inspecting the IAM user that initiated the session. In Lambda, you must investigate the execution role; in ECS startup secret injection, investigate the task execution role.

Cross-account parameters can be shared through supported advanced-tier Parameter Store resource-sharing mechanisms, but cross-account access has its own ARN and authorization rules. A bare name read in the wrong account is not a substitute for using the shared parameter ARN where supported. Confirm that the share and consumer permissions are configured before treating the parameter as missing.

aws sts get-caller-identity --profile production
aws ssm get-parameter --name /shop/prod/payment-url --region us-east-1 --profile production

Jake: "I signed in successfully, so how can the account still be wrong?"

Ethan: "A valid login proves who you are, not which shop drawer you opened. Compare the caller account with the parameter owner."

Use GetParameter for a leaf and GetParametersByPath for a folder

When you know one complete parameter name, GetParameter is the straightforward API. It looks up a single parameter, such as /shop/prod/payment-url. Passing the parent path /shop/prod does not tell the API to retrieve every child.

If your goal is to list a hierarchy, choose GetParametersByPath and supply the parent path. Add the recursive option to include parameters beneath deeper subpaths. Without recursive retrieval, you only receive the applicable direct descendants of the requested path.

GetParameters serves a different need: retrieving several specifically named parameters in one request. Its output distinguishes successful entries from names it cannot resolve. You should inspect both arrays instead of assuming a successful API response proves all requested values existed.

Be careful with IAM for path reads. Granting GetParametersByPath on an ancestor path can expose descendants even if another permission attempts to deny reading a specific descendant through a different action. Design hierarchical boundaries and authorization around that behavior.

aws ssm get-parameter --name /shop/prod/payment-url --region us-east-1
aws ssm get-parameters-by-path --path /shop/prod --recursive --region us-east-1
aws ssm get-parameters --names /shop/prod/payment-url /shop/prod/missing --region us-east-1

Compare GetParameter, GetParameters and GetParametersByPath outcomes

You may see different outputs for the same missing name because the retrieval APIs have different response contracts. GetParameter reports ParameterNotFound as an API error. GetParameters can succeed at the transport level while returning the unresolved names in InvalidParameters.

Your Python or Node.js code must account for that distinction. For GetParameters, inspect InvalidParameters and reconcile it against the requested list. For GetParameter, catch the appropriate service exception and preserve enough context to diagnose account, Region, and name.

A parameter version or label selector introduces a further variation. If you request a version that does not exist, ParameterVersionNotFound can replace the ordinary missing-name error. A selector failure should lead you to inspect the parameter history rather than creating a duplicate parameter.

The lowest-risk diagnostic path reads metadata first and only retrieves decrypted values when necessary. This reduces the chance of accidentally exposing secrets in terminal histories, CI logs, or tickets. It also distinguishes discovery problems from decryption problems.

Separate IAM access denied from a genuinely missing parameter

When permission is the cause, the straightforward SSM call normally reports an access-denied error rather than changing it into ParameterNotFound. That difference matters because hiding every permission error behind a generic “configuration missing” message sends debugging in the wrong direction. Inspect the real service error before making changes.

Application wrappers sometimes catch every SDK exception and return None, a fallback value, or a custom not-found message. That is how authorization failures can appear to be silently swallowed in some software paths. Log a sanitized error code and request context instead of discarding the original exception.

Parameter Store retrieval actions are distinct IAM permissions: ssm:GetParameter, ssm:GetParameters, and ssm:GetParametersByPath. Granting one does not automatically grant the others. Match the action to the API your application actually calls.

Check resource ARN scope, permissions boundaries, organizational service control policies, and the current assumed role when you still receive AccessDenied. An IAM policy naming the right parameter in the wrong Region or account also fails to authorize the call. Prefer the smallest resource scope consistent with your hierarchy design.

aws iam simulate-principal-policy --policy-source-arn arn:aws:iam::111122223333:role/AppRole --action-names ssm:GetParameter --resource-arns arn:aws:ssm:us-east-1:111122223333:parameter/shop/prod/payment-url

Troubleshoot SecureString and KMS permissions separately

If a SecureString exists but retrieval with decryption fails, verify the KMS key permissions. --with-decryption asks Parameter Store to return plaintext rather than ciphertext. For a customer-managed KMS key, the caller needs appropriate permission to use the key in addition to permission to retrieve the parameter.

A successful metadata listing does not prove that your principal can decrypt the value. Likewise, retrieving a SecureString without decryption is not a test of the full production path. Reproduce the application call only in an approved secure environment and keep the value out of logs.

Identify whether the parameter uses the AWS managed SSM key or a customer-managed KMS key. Key policies and grants are particularly important for cross-account or tightly controlled deployments. Errors may involve AccessDeniedException, InvalidKeyId, or a KMS-specific failure rather than ParameterNotFound.

For a Lambda function, inspect the execution role and the KMS key policy. For ECS secret injection, focus on the task execution role rather than the application task role, unless your application itself calls SSM later. Fix the identity doing the retrieval, not the identity most familiar to you.

aws ssm get-parameter --name /shop/prod/api-key --with-decryption --region us-east-1

Jake: "Does ticking decryption make the parameter exist?"

Ethan: "No. It changes how an existing SecureString value is returned. First find the name, then prove the caller can decrypt it."

Find missing parameter versions and labels

When a name includes a suffix such as :3 or :LIVE, it asks for a specific version or label. The base parameter may exist while the selected version or label does not resolve. Your troubleshooting must therefore compare both the base name and the suffix.

Get the latest parameter without a selector to establish that the base object exists. Then inspect get-parameter-history and the configured labels. A label is attached to a specific parameter version and can be moved to another version without changing the parameter name.

Parameter Store maintains version history, but versions can be affected by retention limits and updates. The current history behavior is not a promise that an arbitrarily old version will be available forever. If your application pins a version, plan how that reference is updated during deployments.

CloudFormation dynamic references add a special restriction: Parameter Store labels are unsupported there, unlike ordinary GetParameter selectors. Keep the integration-specific syntax separate from direct CLI experiments. What works in one API parameter is not automatically valid in a CloudFormation template.

aws ssm get-parameter --name "/shop/prod/payment-url:2" --region us-east-1
aws ssm get-parameter --name "/shop/prod/payment-url:LIVE" --region us-east-1
aws ssm get-parameter-history --name /shop/prod/payment-url --region us-east-1

Read a parameter from CLI, Boto3 and Node.js

You can reproduce the same lookup from three clients to isolate where the problem enters. Keep the name and Region identical across runs. If CLI succeeds but your function fails, compare credentials and application code before blaming the service.

Boto3 raises a ClientError whose error code is usually ParameterNotFound for a missing GetParameter name. The AWS SDK for JavaScript v3 exposes a service exception with a name such as ParameterNotFound. CLI formats the error as a line containing “An error occurred (ParameterNotFound) when calling the GetParameter operation.”

Prefer explicit Region configuration for reproducible tests. Your local AWS CLI may read a named profile while deployed Lambda code uses its execution-role credentials. That identity difference is more important than the programming language.

When catching exceptions, preserve the error code and a redacted version of the requested name if it is safe to log. Keep sensitive values and decrypted responses out of logs. A useful failure report tells you which request failed without revealing the secret it was trying to read.

aws ssm get-parameter --name /shop/prod/payment-url --region us-east-1 --query Parameter.Value --output text

import boto3
from botocore.exceptions import ClientError

ssm = boto3.client("ssm", region_name="us-east-1")
try:
    result = ssm.get_parameter(Name="/shop/prod/payment-url")
    print(result["Parameter"]["Value"])
except ClientError as exc:
    print(exc.response["Error"]["Code"])  # ParameterNotFound

import { SSMClient, GetParameterCommand } from "@aws-sdk/client-ssm";
const client = new SSMClient({ region: "us-east-1" });
try {
  const result = await client.send(new GetParameterCommand({
    Name: "/shop/prod/payment-url"
  }));
  console.log(result.Parameter?.Value);
} catch (error) {
  console.error(error.name); // ParameterNotFound
}

You have the naming rules and the Region check; now see them repair one real call, in the order you would use yourself. If your parameter still refuses to appear after this, you will know exactly which of the three questions to ask next.

Worked example: find the real name and repair the call

Imagine Jake sees a parameter under /shop/prod/payment-url in the N. Virginia console. His application attempts shop/prod/Payment-URL in Ohio through a development profile. Those are several distinct mismatches, so changing IAM permissions blindly will not repair the call.

First confirm the console Region and the owning account. Next run the caller identity command using the same profile that executes the failed request. Then explicitly query N. Virginia for parameter names under /shop/prod and copy the exact case-sensitive name.

The repair is to use the fully qualified name, point the SDK to us-east-1, and authenticate as a principal in the correct account with ssm:GetParameter. A final read should return the intended value without a ParameterNotFound exception. For secrets, perform that test without printing plaintext publicly.

This diagnostic can be repeated with an environment-specific parameter such as /shop/stage/payment-url. That comparison is useful because a working staging lookup can reveal a production configuration typo. Keep the changes small enough that you know which mismatch actually caused the failure.

1. Open Systems Manager → Parameter Store and copy the exact parameter name and Region.
2. Run aws sts get-caller-identity --profile production to confirm the account.
3. List the matching hierarchy and locate the copied Name field.
4. Run get-parameter against that exact name with explicit profile and Region.
5. Update the application’s environment configuration and re-run the same read under its runtime identity.

aws sts get-caller-identity --profile production
aws ssm get-parameters-by-path --path /shop/prod --recursive --region us-east-1 --profile production --query "Parameters[].Name"
aws ssm get-parameter --name /shop/prod/payment-url --region us-east-1 --profile production

Fix SSM references in CloudFormation templates

If your CloudFormation stack fails while resolving a Parameter Store reference, inspect the exact syntax used by the template. A plaintext dynamic reference uses a form such as {{resolve:ssm:/shop/prod/payment-url}}. CloudFormation resolves that reference during stack operations rather than your application code running GetParameter directly.

CloudFormation-supplied SSM parameter types are another integration and have their own validation and resolution behavior. They should not be confused with a dynamic reference. A template parameter declared with an AWS::SSM type refers to a Parameter Store entry using that feature’s documented syntax.

CloudFormation must have appropriate permissions to retrieve the parameter, and the reference must resolve in the stack’s Region and appropriate account context. Dynamic references to SSM parameters shared from another account are not supported. A direct CLI lookup in a different Region therefore does not prove the template can resolve its reference.

Error messages can surface as stack events saying a referenced parameter could not be resolved or found. Open the stack Events tab and inspect the first relevant failure rather than only the final rollback state. Record the logical resource and dynamic reference that caused the error.

Resources:
  DemoQueue:
    Type: AWS::SQS::Queue
    Properties:
      QueueName: "{{resolve:ssm:/shop/prod/queue-name}}"

Understand Lambda environment variables and Parameter Store

If your Lambda function uses Parameter Store, distinguish a regular Lambda environment variable from a live SSM lookup. A variable such as PARAMETER_NAME=/shop/prod/api-key simply passes a string to the function. Your code or an extension must retrieve the parameter value; setting the variable does not automatically fetch it.

The AWS Parameters and Secrets Lambda Extension is another supported retrieval path. It reads Parameter Store data through a local extension endpoint and caches values under a configurable TTL. A bad parameter name, role permissions, or stale assumptions about Region can still cause a failed lookup.

Keep plaintext secrets out of Lambda environment variables when a managed secret retrieval design is available to you. Keep the name in the environment and retrieve the encrypted value at runtime with the correct IAM and KMS permissions. Cache thoughtfully so an updated secret becomes visible within your intended timeframe.

If the function succeeds locally but fails in AWS, inspect its execution role, the deployed environment-variable value, and the runtime Region. Your local credentials may have broad Parameter Store access while the function role has narrow permissions. Capture the underlying SDK error before transforming it into a generic application error.

Fix missing Parameter Store references in ECS tasks

If an ECS task fails before your application starts, inspect its stopped reason and initialization error rather than the application logs alone. A task definition can inject a parameter as a secret into a container environment variable. ECS performs that retrieval during task startup.

The secrets field includes a name for the container environment variable and a valueFrom pointing to the Parameter Store parameter name or ARN. A parameter in the same Region can use a name, while a parameter in another Region requires its full ARN. The task execution role needs permission to fetch the referenced secret.

ECS may report a ResourceInitializationError with language about being unable to pull secrets or a retrieval or network problem. That message does not prove the parameter was deleted. Check the referenced ARN, account, Region, execution role, KMS permission, and network path to SSM.

An ECS task does not automatically refresh an injected environment variable when the backing value changes. Start new tasks or force a service deployment to pick up the updated parameter value. That is separate from a ParameterNotFound failure during startup.

{
  "containerDefinitions": [{
    "name": "shop-api",
    "image": "111122223333.dkr.ecr.us-east-1.amazonaws.com/shop-api:latest",
    "secrets": [{
      "name": "API_KEY",
      "valueFrom": "arn:aws:ssm:us-east-1:111122223333:parameter/shop/prod/api-key"
    }]
  }]
}

Why a trailing slash and path depth matter

If you pass a path with a trailing slash to GetParameter, it is not a request to search that folder. GetParameter expects the name of one parameter. Use GetParametersByPath when you mean to retrieve descendants instead of relying on slash normalization.

A parameter whose name is /shop/prod/api-key is not the same as its parent /shop/prod. Likewise, adding / to the end of a leaf name does not identify the same parameter. Treat the exact name as immutable until the lookup succeeds.

When listing parameters, choose a sensible parent such as /shop/prod and use recursive retrieval if your application stores configuration in nested subpaths. Ensure your IAM policy grants the path operation on the expected ancestor. A root or overly broad path is usually unnecessary and may expose more configuration metadata than intended.

Some tooling normalizes slashes when building paths. Inspect the actual string sent to the AWS SDK rather than the environment variable pieces that supposedly produced it. A leading slash accidentally trimmed by a URL or path helper can turn a valid hierarchy into an invalid request.

Diagnose without exposing secrets or trusting incomplete audit trails

When you investigate production failures, keep decrypted SecureString values out of your output. You generally need the parameter name, caller identity, Region, error code, and API operation to diagnose a missing reference. Logging plaintext credentials increases the impact of a simple configuration problem.

CloudTrail does not record ParameterNotFound events for the GetParameter and DeleteParameter actions when the parameter does not exist. The absence of one of those failed requests from CloudTrail is therefore not conclusive evidence that no attempt occurred. Use application logs, CLI output, and SDK error handling together.

Keep successful lookups and missing-name diagnostics separate in monitoring. A surge in missing names after deployment often signals a bad configuration rollout, while isolated failures may indicate environment-specific drift. IAM denial and network errors should have their own alert categories.

If the parameter was deleted, inspect deployment history and applicable backups or version and recovery procedures rather than immediately writing an empty placeholder. Creating a different value under the expected name can make the error disappear while breaking the business function. Restore the intended source of truth first.

When the parameter still cannot be found

If every direct lookup fails, return to the simple questions: does the parameter exist in the target account and Region, and are you asking for its exact stored name? Confirm these independently through the console and a controlled CLI session. If you lack list permissions, ask an authorized administrator to confirm the metadata without sharing the secret.

Next inspect the application-generated request and its credentials. A wrapper can append an environment name, remove a slash, or substitute a default Region. Log the resolved name in a sanitized form and compare the SDK client configuration with your terminal test.

If the direct lookup succeeds, move outward to the consuming service. CloudFormation may use an unsupported selector, ECS may rely on a task execution role, and Lambda may use a different IAM identity or extension cache. The failing layer is now integration-specific rather than Parameter Store itself.

For a support case, gather timestamps, AWS account and Region, request IDs when available, API operation, sanitized parameter path, and the exact error code. Describe the CLI command without secrets and include whether the console shows the parameter. That evidence allows the investigation to focus on the real discrepancy.

Jake: "So the fix is not creating the same key again every time it says missing?"

Ethan: "Right. Find which name, account, and Region the request actually used. Create a new parameter only when the correct resource truly does not exist."

Find hidden AWS CLI profile and shell overrides

If your CLI returns ParameterNotFound on a computer shared by several projects, inspect the AWS profile selection before you reconfigure anything. The --profile argument overrides profile selection on the command, while environment settings can influence credential and Region resolution. You need to know which settings the current terminal process inherited when it launched. A successful login in a different terminal window is not evidence that both processes use the same identity.

For a CLI diagnosis, run aws configure list, then compare with aws configure list --profile production. The output identifies where credential and Region settings are coming from without revealing the underlying secret access key. Follow with aws sts get-caller-identity under the intended profile. The command returns the active account and ARN, making accidental use of a development account much easier to spot.

An AWS SDK in Node.js or Python can resolve credentials differently from your interactive CLI. Lambda and ECS normally rely on IAM roles, while local SDK code can use profile and environment settings. A library that sets the Region explicitly may ignore the default you inspected with the CLI. Print the configured client Region and sanitized caller identity in a controlled diagnostic environment, then remove unnecessary logging afterward.

If you change a profile and the command still fails, add the explicit Region and exact parameter name to the command at the same time. This produces one reproducible request whose destination is no longer implicit. Repeat the lookup only after you can explain which principal and Region it uses. That discipline prevents an accidental parameter creation in the wrong AWS account.

Spot misleadingly similar parameter names

When your configuration is assembled from several variables, the final name may not be what your source code makes you expect. A stage prefix, project prefix, or leading slash can be duplicated or omitted during string concatenation. For example, /shop/prod/prod/token is a different name from /shop/prod/token. Inspect the final string sent into Name, not merely the helper that is intended to create it.

A hierarchy separator is meaningful data in Parameter Store. The resource named /shop/stage/db belongs to a different branch from /shop/prod/db, even when the final leaf is identical. A production release that retains its staging prefix may therefore report a missing parameter despite both environments being healthy. Compare the complete fully qualified names side by side to identify the wrong branch.

Be careful with automatic case transformations. Code that uppercases environment names for display or lowercases them for URL routing can silently change a case-sensitive Parameter Store name. The service does not search for a close match or try alternate case spellings. A full list of parameter names under the correct parent path is more reliable than guessing capitalization.

You can create a short startup validation that asks for essential configuration names before enabling your application to serve requests. The validator should report each missing name with its intended account and Region, not only a generic failure. For encrypted names, check existence and permissions without writing decrypted values to logs. This transforms a confusing runtime incident into a clear deployment-time configuration problem.

Check deletion, expiration, and stale deployment references

If a parameter used to exist but now cannot be found, consider whether it was removed or expired under a policy. Advanced parameters can have policies including expiration, and a parameter removed by policy is no longer available for ordinary GetParameter retrieval. That is an actual missing-resource case rather than a case mismatch. Inspect configuration change records and the intended lifecycle before restoring the parameter.

A deployment may carry an older parameter name in a stored configuration artifact even after your team renamed the live parameter. Lambda published versions, ECS task-definition revisions, and CloudFormation templates can preserve earlier configuration strings. Updating the latest source repository does not retroactively change every deployed copy. You need to identify which version or revision the running consumer actually uses.

Parameter deletion has special consequences for audit work. A failed GetParameter lookup against a nonexistent value is not logged as a CloudTrail event for that failure mode, so the application request trace becomes especially important. Successful administrative changes and related resource events can still help reconstruct the broader sequence, subject to your logging setup. The absence of one expected event is a clue, not an exhaustive audit conclusion.

For a restore, choose the authorized source of truth for the missing value. A placeholder such as an empty string may satisfy a lookup but disrupt databases, authentication, or integrations later in the request. Confirm the value with its owner, then recreate the intended parameter type and encryption configuration if restoration is appropriate. Finally retest the actual application principal instead of only the administrator account.

Trace one real failure without leaking configuration values

When an incident spans CLI commands, Lambda logs, and ECS task events, use one test name and one timestamp to keep the evidence coherent. Ask your application to report the sanitized parameter path, operation, Region, and AWS error code. Logging the decrypted secret just to prove retrieval happened is a habit worth breaking today. For sensitive paths, consider replacing business-specific segments with a trace ID while keeping enough information to correlate the incident.

Begin with metadata discovery under a principal authorized to inspect the relevant hierarchy. If the exact Name appears, make a direct GetParameter request under the failing principal. An access-denied result points toward authorization, while ParameterNotFound suggests request coordinates or an unexpectedly missing resource. If both work, inspect the consuming service and its deployed settings instead.

CloudFormation failures may appear in stack Events, ECS failures in stopped task reasons, and Lambda failures in CloudWatch Logs. Those are different observability surfaces describing a similar underlying configuration dependency. Collect the first failure rather than only the last cascading error, which may simply say an application did not initialize. Keep the direct Parameter Store command as a baseline that can be repeated after the fix.

Finally distinguish a request that cannot find the parameter from one that cannot reach the SSM service endpoint. A timeout, DNS failure, or network route problem is not proof that the name is wrong. This distinction matters in private subnets using VPC endpoints and restricted network policies. Check connectivity only after the error text and request destination justify it.

Avoid unnecessary parameter creation and billing surprises

If a lookup fails, resist the impulse to create a second copy in every Region as a quick workaround. That practice can lead to conflicting configuration sources, and later changes may update one value but not the others. Define which account and Region owns the configuration for each environment. Then point all consumers at that intended source or use a deliberate sharing strategy.

Standard and advanced Parameter Store tiers have different capabilities and pricing implications. Advanced parameters support features such as parameter policies and resource sharing, while ordinary parameters often fit simpler configuration uses. Before promoting or duplicating a large set of parameters, review the current regional pricing and tier requirements. A naming failure is not itself a reason to pay for a more expensive tier.

Throughput is another distinct concern: high request volume can produce throttling symptoms rather than a legitimate ParameterNotFound response. Add an appropriate caching layer when your use case repeatedly fetches unchanged values, and make cache expiry deliberate. The Parameters and Secrets Lambda Extension is one option for Lambda workloads. Caching a typo will not repair the underlying name, but it can reduce repeated legitimate reads after the configuration is corrected.

For the phone-shop scenario, the operational cost of downtime is more immediate than the API request itself. If 20 booking attempts each require the same missing configuration value, repeatedly retrying that unchanged typo only repeats the failure. A deployment validation of the intended parameter would have caught the problem before the shop opened. Treat the fix as part of a repeatable release checklist rather than a one-time command.

Choose the right fix from the error you actually see

You can eliminate many false leads by matching the error shape to the next diagnostic action. A missing-name response needs a name, account, and Region comparison. An access-denied response needs IAM analysis. A KMS failure needs key access work rather than a new Parameter Store path.

One subtle case is a successful GetParameters API call with entries in InvalidParameters. Your application may continue because the SDK did not throw an exception, and the missing result appears only later as a null or empty configuration field. Check the arrays as part of the retrieval itself. This is an application correctness issue as much as a troubleshooting issue.

Another subtle case is a correct direct read combined with an ECS container startup failure. The task execution role may lack permission even though the developer profile succeeds. Similarly, a successful CLI call does not automatically mean CloudFormation can resolve a dynamic reference in its own execution context. Trace the permissions belonging to the consuming service.

Use the comparison table to choose a first action, then gather evidence before making modifications. You can return to a broader investigation if the direct check does not match the symptom. The table is not a substitute for the complete error payload, but it gives your next command a clear purpose.

If the direct CLI read succeeds but the integration still fails, write down the exact deployed configuration revision before you edit anything. A Lambda alias can point to a version with an older environment variable, and an ECS service can still run a task-definition revision that references the previous parameter name. For CloudFormation, the stack’s active template can differ from your local file. Identifying these revisions prevents the most common false conclusion: that a successful terminal command proves production is already fixed.

When you repair the configuration, make one controlled change and observe the matching service event. In ECS that may mean registering a corrected task definition and deploying it; in Lambda it may mean updating the configuration and publishing or routing to the intended version. In CloudFormation, use a planned stack update with the corrected reference. After the change, confirm that the actual production principal can retrieve the parameter rather than stopping after a successful administrator test.

Keep a short incident record containing the wrong and corrected parameter names, the originating Region, and the executing role, with sensitive names redacted where needed. This gives your team a specific safeguard to add to future deployment checks. If the same mismatch comes back, the next developer will know whether to look at an old task definition, a profile override, or a malformed hierarchy. The goal is not merely to silence the exception but to eliminate the configuration drift that produced it.

1. Record the name, Region, account, API action, and observed AWS error code.
2. Test the exact name under the intended runtime identity without disclosing decrypted values.
3. Update the deployed configuration and identify the active version or revision.
4. Re-run the consumer operation and inspect the service-specific error surface.
5. Add a predeployment existence check for critical parameter references.

Frequently asked questions

What does ParameterNotFound mean in AWS SSM?

It means a GetParameter lookup could not resolve the requested parameter in its account and Region. Compare the full name and case, then the calling identity and Region. Different APIs may report missing entries differently.

Why does Parameter Store show my parameter in the console but not CLI?

The console and CLI often point to different Regions or accounts. Run aws configure list and aws sts get-caller-identity, then specify an explicit Region and profile. Copy the parameter name exactly from the console.

Are SSM Parameter Store names case-sensitive?

Yes. A name such as /shop/Prod/Key differs from /shop/prod/key. Use the exact stored capitalization throughout the call.

Does an SSM parameter name need a leading slash?

Hierarchical names require a leading slash, such as /shop/prod/key. Root-level parameters can use a plain name or a slash-prefixed name. A hierarchy like shop/prod/key without the initial slash is not fully qualified.

What is the SSM parameter name length limit?

The practical limit is 1,011 characters including the ARN prefix preceding the supplied parameter name. API field models may show 2,048 characters because part of the allowance is reserved internally. The usable name length depends on the ARN prefix.

Can an SSM parameter start with aws or ssm?

Parameter names cannot use the reserved aws or ssm prefixes, ignoring case. The restriction also covers hierarchy names such as /aws/example. Such names fail creation validation.

How do I list all SSM parameters under a path?

Use aws ssm get-parameters-by-path --path /shop/prod --recursive. Add an explicit --region flag if the CLI Region might differ from the console. IAM must permit GetParametersByPath on the requested hierarchy.

What happens if GetParameters contains one missing name?

GetParameters can return valid Parameters and put unresolved names in InvalidParameters without raising a ParameterNotFound exception for the whole batch. Check both response arrays. GetParameter instead returns a missing-name error for one requested name.

What is the difference between GetParameter and GetParametersByPath?

GetParameter retrieves one fully qualified parameter name. GetParametersByPath retrieves parameters beneath a hierarchy path, optionally recursively. Passing a parent directory to GetParameter does not list its children.

Does a trailing slash matter for SSM parameters?

Yes, the exact name and the path argument have different meanings. A trailing slash is not a universal alias for a leaf parameter name. Use the correct parent path with GetParametersByPath and the exact leaf name with GetParameter.

Can IAM denial look like ParameterNotFound?

An ordinary SSM IAM denial normally has an access-denied error, not ParameterNotFound. But application wrappers may swallow or rewrite SDK errors and make permissions look like a missing value. Preserve and inspect the original AWS error code.

Why does SecureString fail when the parameter exists?

Reading a SecureString with decryption can require KMS permission in addition to SSM retrieval access. Inspect the key configuration and the actual runtime role. A decryption failure should be investigated separately from an absent parameter.

How do I read a particular SSM parameter version or label?

Pass a selector such as /shop/prod/key:3 or /shop/prod/key:LIVE to GetParameter. Inspect version history and label assignments if the lookup fails. CloudFormation dynamic references have separate selector restrictions.

Why does CloudFormation say my SSM parameter cannot be resolved?

The referenced parameter may be absent from the stack Region or account, or the template may use the wrong reference syntax. Check permissions, the exact name, and the first failing stack event. CloudFormation does not support SSM dynamic references to parameters shared from another account.

Why does ECS report ResourceInitializationError for an SSM parameter?

ECS may be unable to inject the parameter because of the name or ARN, task execution role permissions, KMS permissions, or connectivity. Review the stopped task reason and task definition secrets field. Injected values are resolved at task startup.

Can Lambda environment variables automatically resolve SSM parameter names?

A regular Lambda environment variable holding an SSM parameter name does not automatically fetch its value. Your code or the Parameters and Secrets Lambda Extension must perform retrieval. Use the Lambda execution role permissions and intended Region.

If your next deployment trips over ParameterNotFound, begin with the exact name, account, and Region before changing security settings or recreating data. That sequence would have saved Jake a long afternoon at the repair counter, and it is a dependable starting point for your own systems. If your failure comes from CloudFormation, Lambda, or ECS, take the confirmed direct lookup into that integration and follow the specific execution identity. I hope your next configuration rollout finds every parameter on the first try.

Revision note. Written October 15, 2026, with the 15-level hierarchy and the 1,011-character name limit as Parameter Store states them. The ladle knows nothing of the broth, says a Tamil proverb; the console sees your parameter, your code must still ask by its exact name.