Comprehensive reference for all error messages, HTTP status codes, and failure modes.
These errors originate from the MDE API and are handled by the rate limiter (Rate-Limiter.ps1) or surfaced by individual modules.
| Code | Error | Cause | Fix |
|---|---|---|---|
| 400 | Bad Request | Invalid command syntax, wrong argument types, case-sensitive command names (e.g., runscript instead of RunScript), payload exceeding API limits, or ActiveRequestAlreadyExists (another LR action running on the machine). |
For syntax: check command. For ActiveRequest: shell auto-handles — official mode cancels the conflicting action (unless it's ours), internal mode waits. Fixed backoff (10s, then 15s) up to 12 retries. |
| 401 | Unauthorized | Bearer token expired (official) or sccauth cookie expired (internal). | Shell auto-refreshes for client credentials, credential+TOTP, and passkey. For other methods, run connect to re-authenticate. |
| 403 | Forbidden | Insufficient API permissions or portal role. Device group not configured for Live Response. | Official: Verify app registration has Machine.LiveResponse and Library.Manage scopes. Internal: Verify Security Operator role. Check device group remediation level. |
| 404 | Not Found | Machine ID no longer valid, library file missing, or action ID not found. | Run machines refresh to reload. For library: library refresh. |
| 409 | Conflict | Library file already exists with the same name. | Delete the old file first with library delete <name>. Shell auto-overrides when uploading stubs. |
| 413 | Payload Too Large | Command payload exceeds API size limit (~30KB reliable, 40KB+ rejected). | Upload as library script: library upload ./script.ps1 then run script.ps1. |
| 429 | Too Many Requests | Rate limit exceeded (10 LR commands/min or 100 library uploads/min). | Shell handles automatically: sleeps for Retry-After header value (default 35s) and retries up to 5 times. No user action needed. |
| 502 | Bad Gateway | Transient server error. | Shell retries with exponential backoff (2^attempt * 3s, capped at 60s, up to 5 retries). If persistent, wait a few minutes. |
| 503 | Service Unavailable | MDE API temporarily unavailable. | Shell retries with exponential backoff (capped at 60s, up to 5 retries). |
| 504 | Gateway Timeout | Upstream timeout. | Shell retries automatically. If persistent, check MDE service health. |
Errors displayed in the interactive REPL via [Error] prefix (red text).
| Error Message | When | Fix |
|---|---|---|
[Error] No machine selected. Use 'machines' to pick one, or 'connect <name>' to connect directly. |
Any command requiring a target machine when none is selected. | Run machines or connect <name>. |
[Error] Executor stubs not uploaded. Arbitrary commands require B64 stubs. |
Running a non-native command when stubs failed to upload. | Run connect to retry, or library upload stubs/executor_b64.ps1 manually. |
[Error] Usage: library upload <local-path> |
library upload without a path. |
Provide the path: library upload ./myscript.ps1. |
[Error] Usage: library delete <filename> |
library delete without a name. |
Provide the name: library delete old_script.ps1. |
[Error] Usage: library download <filename> |
library download without a name. |
Provide the name: library download myscript.ps1. |
[Error] Usage: actions cancel <id> |
actions cancel without an ID. |
Provide a full or partial GUID: actions cancel abc123. |
[Error] Command could not complete -- another action is blocking this machine. |
ActiveRequestAlreadyExists persisted after 12 retries. |
Check actions and actions cancel <id> to clear. |
[Error] Authentication expired. |
401 during command execution. | Type connect to re-authenticate. |
[Error] Permission denied. |
403 during command execution. | Check scopes (official) or role (internal). Check device group remediation level. |
[Error] Machine not found. |
404 for the selected machine. | Run machines refresh. |
[Error] Rate limited by MDE. |
429 persisted after all retries. | Wait 60 seconds and try again. |
[Error] Bad request -- the MDE server rejected this command. |
400 from invalid syntax. | Check command syntax. Type help commands. |
[Error] MDE server error (500). |
Server-side issue. | Retry. If persistent, check MDE service health. |
[Error] Could not connect to the target machine. |
Session creation failed (machine offline, SenseIR down). | Check machine is online. Run machines refresh to check health. |
[Error] Authentication failed: <details> |
Initial auth fails at startup. | Check credentials, config path, and connectivity. |
'<verb>' is not a shell command. Did you mean '<close match>'? |
Input looks like a typo of a shell command. | Fuzzy match suggestion. The command is still sent to the target -- use the correct shell command if intended. |
| Message | When | Fix |
|---|---|---|
[Timeout] The MDE server timed out this command. |
Server reported TimeOut status. |
Use simpler commands, check machine connectivity. Long operations (findfile, analyze, trace) can take 10-30 minutes. |
Command timed out after <N>s |
Client-side poll exceeded timeout. | Increase commandTimeoutSeconds in config, or check machine responsiveness. |
| Error Message | When | Fix |
|---|---|---|
Config file not found: <path> |
-Config points to nonexistent file. |
Verify path. Copy shell-config.example.json. |
Config missing required fields: official.tenantId, official.clientId |
Config missing tenant or client ID. | Add fields under official key. |
Config missing official.clientSecret (or set official.useDeviceCode=true) |
No secret and no device code. | Add clientSecret or set "useDeviceCode": true. |
Client credentials auth failed: <details> |
OAuth2 token request fails. | Verify tenantId, clientId, clientSecret. Check admin consent. |
Device code request failed: <details> |
Device code init fails. | Check IDs. Ensure app allows public client flows. |
Device code flow timed out |
User did not authenticate in time. | Re-run and authenticate promptly in browser. |
Not connected to Official API. Run Connect-MDEOfficial first. |
API call before auth. | Run connect. |
Token expired and no refresh params stored. |
Device code token expired. | Re-authenticate. Use client credentials for unattended use. |
| Error Message | When | Fix |
|---|---|---|
Not connected to Internal API. |
API call before auth. | Run connect. |
Internal session object is missing. |
State corrupted. | Run connect. |
Authentication failed (<code>): Invalid username or password. |
Wrong credentials (50126). | Verify UPN and password. |
Authentication failed (50053): Account is locked. |
Too many failures. | Wait for lockout to expire. |
Authentication failed (50057): Account is disabled. |
Account disabled. | Contact admin. |
Authentication failed (50055): Password has expired. |
Password needs change. | Update password. |
Authentication failed (53003): Blocked by Conditional Access policy. |
CA policy blocks login. | Check CA policies. Shell uses browser-compatible UA. |
Authentication failed (50034): User account not found. |
UPN does not exist. | Verify username. |
MFA BeginAuth failed |
MFA challenge init fails. | Check MFA method is registered. |
Push notification denied or failed |
Authenticator push denied/timed out. | Approve promptly. |
Push notification timed out after <N> seconds. |
No response within 180s. | Re-run and approve promptly. |
Failed to complete authentication flow. Please verify the ESTSAUTHPERSISTENT cookie value. |
ESTS cookie invalid/expired. | Get fresh cookie from browser DevTools. |
Session information is not sufficient for single-sign-on |
ESTS cookie cannot SSO (50058). | Use incognito browser to get new cookie. |
TenantId is required for TAP authentication |
TAP without resolvable tenant. | Provide -TenantId or use a UPN with a resolvable domain. |
[Auth] Portal session expired (sccauth). |
~1hr session expired, cannot auto-refresh. | Re-connect with credential+TOTP, passkey, or fresh cookie. |
[Auth] Silent re-auth failed: <details> |
Auto re-auth failed. | Check TOTP secret is valid. Re-authenticate manually. |
These appear as yellow warnings during execution. The rate limiter (Rate-Limiter.ps1) handles them transparently.
| Message | Trigger | Behavior |
|---|---|---|
[RateLimit] API rate limit reached — automatically retrying in <N>s (attempt X/5)... |
HTTP 429 response. | Sleeps for Retry-After (default 35s), retries up to 5 times. |
[Conflict] Another command is running on this machine — checking ownership (attempt X/12)... |
ActiveRequestAlreadyExists in official mode. |
If the conflicting action is another tool's: cancel it. If it's ours (comment contains "LaraC2"): let it finish. |
[Conflict] Another command is running on this machine — waiting for it to finish (attempt X/12)... |
ActiveRequestAlreadyExists in internal mode (no cancel capability). |
Wait-only. |
[Retry] Waiting <N>s before next attempt... |
After ActiveRequest handling. | Fixed schedule: 10s on first retry, then 15s for subsequent retries (NOT exponential). |
[Network] Transient error (<code>) — retrying in <N>s (attempt X/5)... |
502/503/504 or connection timeout. | Exponential backoff 2^attempt * 3s, capped at 60s, up to 5 retries. |
Max retries (5) exceeded. |
All retry attempts failed for non-ActiveRequest errors. | Check machine connectivity, API status, auth state. |
Max retries (12) exceeded. |
ActiveRequest persisted. | Check actions and actions cancel <id>. |
| Error Message | When | Fix |
|---|---|---|
Failed to fetch machines (internal): <details> |
Internal API list fails. | Run connect to re-authenticate. |
Failed to fetch machines (official): <details>. Check Machine.Read permission. |
Official API list fails. | Verify Machine.Read or Machine.Read.All permission. |
[Machines] No machines found. |
Empty machine list. | Check machines are enrolled and visible. |
[Machines] No machine matching '<query>'. |
No match for substring. | Check spelling. Run machines for full list. |
| Error Message | When | Fix |
|---|---|---|
Failed to fetch library (internal): <details> |
Internal listing fails. | Re-authenticate. |
Failed to fetch library (official): <details> |
Official listing fails. | Verify Library.Manage permission. |
[Library] Empty. |
No files in library. | Upload with library upload. |
File not found: <path> |
Local file path invalid. | Check the file path. |
[Library] File '<name>' is <size> MB -- exceeds documented 20MB API limit. |
File over 20MB. | Use Defender portal for larger files. |
[Library] <name> already exists |
Upload conflict (409). | Delete first or use override. |
[Library] <name> not found. |
Delete/download targets nonexistent file. | Run library refresh. |
[Library] File content download not available via official API. |
library download in official mode. |
Switch to internal mode. |
| Error Message | When | Fix |
|---|---|---|
No machine selected. Run 'machines' first. |
Actions without machine. | Select a machine. |
Failed to fetch actions: <details> |
API list fails. | Re-authenticate. |
[Actions] No active action matching '<id>'. |
Cancel ID does not match. | Run actions to see IDs. |
Cancel failed: <details> |
Cancel request fails. | Action may have completed. |
| Error Message | When | Fix |
|---|---|---|
Session expired during command execution. |
Internal session died mid-command. | Re-run; shell auto-reconnects. |
Command timed out after <N>s |
Timeout exceeded. | Simplify command or increase timeout. |
Portal session expired. Re-run: connect |
Auth expired, no auto-refresh. | Re-authenticate manually. |
Prior command in batch failed -- subsequent commands not executed |
Batch cascade failure. | Fix failing command and re-run. |
Library script not found on Linux/macOS target. |
.sh stub not synced. | Upload via Internal API or Defender portal UI. Official API uploads do not sync .sh files to non-Windows machines. |
[Command] '<verb>' is Windows-only but target OS is <OS>. |
Windows command on non-Windows target. | Use a compatible command. |
[Command] Large payload (~<N>KB after B64). |
Payload over ~30KB. | Split or use library upload + run. |
| Message | When | Fix |
|---|---|---|
[Init] Unsigned script execution is DISABLED in this tenant. |
LR config shows AllowUnsignedScripts = false. |
Admin: Settings > Endpoints > Advanced Features > Live Response unsigned script execution. |
[Init] Library stubs check failed: <details> |
Auto-upload failed. | Retry with connect, or upload manually. |
[Init] Arbitrary commands will not work until executor stubs are uploaded. |
Stubs missing. | library upload stubs/executor_b64.ps1 and .sh. |
[Shell] Could not parse config '<path>': <details> |
Invalid JSON in config. | Fix JSON syntax. |
| Error | Cause | Fix |
|---|---|---|
ambiguous redirect on Linux/macOS |
.sh stub has CRLF line endings. |
Re-save with LF line endings and re-upload. |
script not found in library on Linux/macOS |
Official API upload did not sync .sh file. |
Upload via Internal API (portal) or Defender portal UI first. |
numeric argument required on Linux/macOS |
CRLF in .sh stub. |
Same as ambiguous redirect -- fix line endings. |