Troubleshooting

Command l not found

Make sure Node.js 22+ is installed, then run:

npm install -g @ricko-v/l
l --version
l --help

Open a new terminal after installing. If it still fails, check that the global npm executable directory is on your terminal's PATH.

Not authenticated. Run l login first.

The session file is missing. Run:

l login

For named profiles, use the name from the error, for example l login --profile production. A project profile does not automatically use the default session even when default is already logged in. Verify your identity with l whoami --profile production.

If login just finished, make sure the command runs as the same operating system user, since sessions are stored in that user's home directory.

Invalid AWS session. Run l login again.

The contents of ~/.l/session.json are invalid, incomplete, or contain an invalid expiry date. Sign in again. Do not try to repair credentials manually. Named profiles use ~/.l/profiles/<profile>/session.json.

Cannot read AWS session

The file exists but cannot be read. Check directory/file ownership and permissions. Expected values on macOS/Linux:

ls -ld ~/.l
ls -l ~/.l/session.json

Only the user should be able to access the directory (0700) and read/write the file (0600). The next login also attempts to tighten permissions.

Wrong or missing profile

Check profile in the nearest config and the command's --profile option. The option overrides the project choice. Profile names are lowercase without spaces, dots, or path separators. This CLI does not use AWS_PROFILE.

l whoami --profile production
l login --profile production

Named sessions live in ~/.l/profiles/<profile>/session.json. Avoid symlinks in profile directories/files because they are rejected. If you need another account for code already pulled, use a separate project so the ARN baseline stays consistent. See multiple profiles for selection rules and compatibility with older sessions.

Login timeout

AWS login timed out appears if no callback arrives within five minutes.

Check that:

• the browser opened successfully;
• l login is still running;
• AWS Sign-In is not blocked by an extension or network policy;
• the redirect to 127.0.0.1 is reachable from the same browser.

Then run l login again. Each attempt creates new state, a PKCE verifier, and a DPoP key.

OAuth state mismatch

The callback belongs to another flow or its URL is incomplete. Return to the tab opened by your latest login attempt. If it still fails, close the old flow and run l login again.

Session refresh failed

When AWS returns The refresh token has expired, the CLI displays:

Refreshing AWS session...
AWS session expired for profile "default": the refresh token has expired. Run `l login --profile default` to sign in again, then retry your command.

Commands requiring credentials stop with an error; l init displays the message and still offers manual configuration. Run l login, then retry the original command. Network and permission failures keep their original errors so they are not confused with session expiry.

Refresh tokens may expire or be rejected. Sign in again:

l login
l whoami

AccessDeniedException

Login succeeded, but the identity lacks permission for the requested operation.

Also check the account and region using l whoami. The person managing AWS account access must correct the IAM policy.

Function not found

Make sure the name and region are correct:

l whoami
l lambda list --prefix name-prefix

The Lambda region follows --region, the project, then the login session. Check l.config.json or try l lambda list --region <region>. The region in l whoami is the auth region and may differ from the resource region.

Init requires an interactive terminal

Run l init directly in a terminal. Piping or redirecting stdin/stdout is not supported. Enter a choice number and press Enter; Ctrl+C cancels input.

Windows and Linux

• Windows: EPERM/EBUSY during rename or folder replacement: close processes holding target files and check folder permissions. Conflict checks still apply; do not delete config/state to force an update.
• Upcoming release — Windows: rejected profile names: avoid device names such as con, nul, com1, and lpt1. This rule applies on other operating systems for portability too.
• Upcoming release — Windows: Lambda executables: executable modes for known files follow the deployment baseline. New files use 0644; prepare new executables on Linux/WSL or macOS. See Windows and executable permissions.
• Upcoming release — Linux: browser does not open: open the displayed login URL in a browser on the same computer. The CLI keeps waiting for the callback; a browser on another computer over SSH cannot automatically reach the CLI process's 127.0.0.1.
• Native dependencies: the CLI does not run builds. Prepare binaries/dependencies for Linux and the target Lambda architecture, not your local Windows/macOS binaries.

References: Node.js filesystem caveats, Windows filename rules.

Termux: EACCES permission denied link

If the message mentions .l.config-*.tmp and l.config.json, l init failed while saving a new config, after successfully writing the temporary file. Android may restrict hard links in Termux. The upcoming fix tries an exclusive copy when hard links are rejected; existing configs are still not overwritten. This fix is not included in npm version 2.0.0.

While waiting for the fix, create l.config.json manually in your project folder only if it does not exist, using:

{
  "version": 1,
  "name": "my-project",
  "region": "ap-southeast-1",
  "profile": "default"
}

Adjust the name, region, and profile, then run l init again to choose a function/prefix. Updating an existing config uses rename rather than a hard link. If the file already exists, inspect and edit it; do not overwrite it with this example. If copying also produces EACCES, check folder/file write permissions.

Reference: Termux hard link report.

Init cannot fetch the Lambda list

Make sure you have run l login and have lambda:ListFunctions permission in the selected resource region. If the list is empty or the request fails, the wizard returns to the mode menu. Manual names, prefixes, and skipping are still available.

Project config is invalid or changed during init

Invalid l.config.json stops the process so the old file remains available. Fix its format using project configuration, then retry.

If the file changed while the wizard was running or you see EEXIST, review the latest config and run l init again. Existing configs require update approval.

Pull or push failed

• Preflight failed: a target failed the initial checks. No function code or baseline has changed; fix targets marked failed, then retry.
• Sync stopped after a failure: review the summary. Targets marked success remain applied; skipped targets have not run. Check AWS for a failed push because upload may have been accepted before the error. Retry only target names that still need work.
• Remote revision conflict: back up local changes, pull, then merge changes before pushing again. --yes does not bypass conflicts.
• Local changes need explicit review: retry pull without --yes, review changes, then confirm backup/replacement if appropriate.
• Account or region differs: use the original login/region or a separate project.
• Update timed out: check AWS first; code may have been uploaded even though local state has not advanced.
• Another sync may be running: inspect the process in .l/sync.lock before removing a stale lock.

See pull and push for recovery details and package size limits.