> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formae.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot a failed command

> Diagnose a failed apply or destroy with the detailed status layout: find the resource that broke and read its provider error.

An apply or destroy can come back failed: a resource the cloud rejected, a
permissions problem, a name clash. formae records exactly which resource broke
and why. This guide shows how to read it.

## See what broke

When a command comes back failed, switch to the detailed layout to see which
resource broke and its error:

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
formae status command --output-layout=detailed
```

<div className="fa-term">
  <div className="fa-term-body">  <span style={{fontWeight:'600'}} /><span style={{color:'rgb(232,232,232)',fontWeight:'600'}}>formae</span> <span style={{fontWeight:'600'}} /><span style={{color:'rgb(255,133,51)',fontWeight:'600'}}>status command</span>                                                                                     <span style={{color:'rgb(129,209,219)'}}>↻ live</span><br /><span style={{color:'rgb(85,85,102)'}}>────────────────────────────────────────────────────────────────────────────────────────────────────────────────────</span><br /><span style={{color:'rgb(85,85,102)'}} /><span style={{color:'rgb(85,85,102)',fontWeight:'600'}} /><span style={{color:'rgb(170,170,170)',fontWeight:'600'}}>     ID                          Command   Mode        Progress                         ✓    ✗    ◐    ○    Time</span><br /><span style={{color:'rgb(170,170,170)',fontWeight:'600'}} /><span style={{color:'rgb(248,113,113)'}}>✗    </span><span style={{color:'rgb(129,209,219)'}}>3GnWjXDeziP4JuLFNnub3f23hGf </span><span style={{color:'rgb(232,232,232)'}}>apply     patch       failed 0/1                       0    1    0    0    00:20</span><br /><span style={{color:'rgb(232,232,232)'}} /><span style={{color:'rgb(85,85,102)'}}>────────────────────────────────────────────────────────────────────────────────────────────────────────────────────</span><br /><span style={{color:'rgb(85,85,102)'}} /><br /><span style={{color:'rgb(85,85,102)'}}>  </span><span style={{color:'rgb(85,85,102)',fontWeight:'600'}} /><span style={{color:'rgb(255,133,51)',fontWeight:'600'}}>▌ Resources</span><br />  <span style={{color:'rgb(170,170,170)'}}>      </span><span style={{color:'rgb(170,170,170)',fontWeight:'600'}} /><span style={{color:'rgb(232,232,232)',fontWeight:'600'}} /><span style={{color:'rgb(232,232,232)',fontWeight:'600'}}>Label ▲                                               </span><span style={{color:'rgb(170,170,170)'}}>Type                                Operation   Time</span><br />   <span style={{fontWeight:'600'}} /><span style={{color:'rgb(248,113,113)',fontWeight:'600'}} /><span style={{color:'rgb(248,113,113)',fontWeight:'600'}}>✗</span>    <span style={{color:'rgb(252,165,165)'}}>incident-logs</span>                                         <span style={{color:'rgb(252,165,165)'}}>AWS::S3::Bucket</span>                     <span style={{color:'rgb(252,165,165)'}}>create</span>      <span style={{color:'rgb(252,165,165)'}}>00:20</span><br />      <span style={{color:'rgb(248,113,113)'}}>test already exists (Service: S3, Status Code: 0, Request ID: null)</span><br /><br /><span style={{color:'rgb(85,85,102)'}}>────────────────────────────────────────────────────────────────────────────────────────────────────────────────────</span><br /><span style={{color:'rgb(85,85,102)'}} />  <span style={{fontWeight:'600'}} /><span style={{color:'rgb(129,209,219)',fontWeight:'600'}}>→←</span><span style={{color:'rgb(153,153,153)'}}>: column</span>  <span style={{fontWeight:'600'}} /><span style={{color:'rgb(129,209,219)',fontWeight:'600'}}>s</span><span style={{color:'rgb(153,153,153)'}}>: toggle sort</span>  <span style={{fontWeight:'600'}} /><span style={{color:'rgb(129,209,219)',fontWeight:'600'}}>space</span><span style={{color:'rgb(153,153,153)'}}>: expand</span>  <span style={{fontWeight:'600'}} /><span style={{color:'rgb(129,209,219)',fontWeight:'600'}}>d</span><span style={{color:'rgb(153,153,153)'}}>: details</span>  <span style={{fontWeight:'600'}} /><span style={{color:'rgb(129,209,219)',fontWeight:'600'}}>esc</span><span style={{color:'rgb(153,153,153)'}}>: back</span>  <span style={{fontWeight:'600'}} /><span style={{color:'rgb(129,209,219)',fontWeight:'600'}}>q</span><span style={{color:'rgb(153,153,153)'}}>: quit</span>                                <span style={{fontWeight:'600'}} /><span style={{color:'rgb(129,209,219)',fontWeight:'600'}}>?</span><span style={{color:'rgb(153,153,153)'}}>: help</span></div>
</div>

Here the create failed because the bucket name was already taken: the error line
reads `test already exists (Service: S3, Status Code: 0, Request ID: null)`.
Pick a name that is not in use and apply again. The detailed layout gives you the
resource label, its type, the operation formae attempted, and the provider error
verbatim, so you can act on the cause rather than guess at it.

## Find a specific failure

With no query, `formae status command` reports your most recent command. To find
a specific failure, filter:

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
formae status command --query="status:Failed"
```

<div className="fa-term">
  <div className="fa-term-body">  <span style={{fontWeight:'600'}} /><span style={{color:'rgb(232,232,232)',fontWeight:'600'}}>formae</span> <span style={{fontWeight:'600'}} /><span style={{color:'rgb(255,133,51)',fontWeight:'600'}}>status command</span>                                                                                     <span style={{color:'rgb(129,209,219)'}}>↻ live</span><br /><span style={{color:'rgb(85,85,102)'}}>────────────────────────────────────────────────────────────────────────────────────────────────────────────────────</span><br /><span style={{color:'rgb(85,85,102)'}} /><span style={{color:'rgb(85,85,102)',fontWeight:'600'}} /><span style={{color:'rgb(232,232,232)',fontWeight:'600'}}> ▲   </span><span style={{color:'rgb(170,170,170)',fontWeight:'600'}}>ID                          Command   Mode        Progress                   ✓    ✗    ◐    ○    Time    Age</span><br /><span style={{color:'rgb(170,170,170)',fontWeight:'600'}} /><span style={{color:'rgb(252,165,165)'}} /><span style={{color:'rgb(252,165,165)'}}>✗    3Fsu27ZRJNwlWDPYesoTXwk7hXq apply     reconcile   failed 2/3                 2    1    0    0    01:06   20d</span><br /><span style={{color:'rgb(252,165,165)'}} /><span style={{color:'rgb(248,113,113)'}} /><span style={{color:'rgb(248,113,113)'}}>✗    3FsrQqQrqYKrgjzCVo6Nvch62ns apply     reconcile   failed 28/29               28   1    0    0    12:36   20d</span><br /><span style={{color:'rgb(248,113,113)'}}>✗    3FsqCdKnO2Qh0jAFGMfiiXQi5Ri apply     reconcile   failed 22/30               22   8    0    0    01:10   20d</span><br /><span style={{color:'rgb(248,113,113)'}}>✗    3FqBvbCCS1F5wgQUVFszRR4Rwgh destroy   -           failed 6/7                 6    1    0    0    01:48   21d</span><br /><span style={{color:'rgb(248,113,113)'}}>✗    3FpfrjzJvGkq1V1rcjJanxrY4qF apply     reconcile   failed 26/29               26   3    0    0    04:55   22d</span><br /><span style={{color:'rgb(248,113,113)'}}>✗    3FpPTiEKK7nXvtGKBsSaryi9ZKr apply     reconcile   failed 0/13                0    13   0    0    00:01   22d</span><br /><span style={{color:'rgb(248,113,113)'}}>✗    3FpNiE3GNCMye3uVJ79tScbvR5O apply     reconcile   failed 15/28               15   13   0    0    01:48   22d</span><br /><span style={{color:'rgb(248,113,113)'}}>✗    3FkfhkcC8ESxEJRneolwBFXFKuS apply     reconcile   failed 5/9                 5    4    0    0    00:51   23d</span><br /><span style={{color:'rgb(248,113,113)'}}>✗    3FjMidSHpIDv3qpv8HsYUmQvfwM apply     reconcile   failed 24/26               24   2    0    0    02:24   24d</span><br /><span style={{color:'rgb(248,113,113)'}}>✗    3FjLo0gs0Rp73tLjOEnVzY4kYnt apply     reconcile   failed 12/14               12   2    0    0    01:33   24d</span><br /><span style={{color:'rgb(248,113,113)'}} /><br /><span style={{color:'rgb(248,113,113)'}} /><span style={{color:'rgb(85,85,102)'}}>────────────────────────────────────────────────────────────────────────────────────────────────────────────────────</span><br /><span style={{color:'rgb(85,85,102)'}} />  <span style={{color:'rgb(129,209,219)'}}>/</span> <span style={{color:'rgb(170,170,170)'}}>status:Failed</span>                                                                                    <span style={{color:'rgb(153,153,153)'}}>/: edit query</span><br /><span style={{color:'rgb(85,85,102)'}}>────────────────────────────────────────────────────────────────────────────────────────────────────────────────────</span></div>
</div>

Command queries filter on `id`, `status`, `client`, `command`, and `stack`; on a
shared agent, add `client:me` to see only your own commands. For pipelines, add
`--output-consumer=machine --output-schema=json`.

## See also

* [Cancel a running command](/documentation/guides/cancel-a-running-command): stop a command you triggered by mistake, or one that is stuck.
* [Incidents and recovery](/documentation/guides/incidents-and-recovery): fix a live incident with a patch and settle up afterwards.
* [CLI reference](/documentation/reference/cli): full flags for `apply`, `destroy`, `status`, and `cancel`.
