# Troubleshooting Contracts

This guide covers common contract lifecycle failures, including acceptance errors, invalid state transitions, and blocked settlement actions.

## Symptoms

- Cannot accept a contract
- `invalid_transition` errors on state changes
- Pickup or refund actions are blocked

## Diagnostic Checklist

### 1. Contract status does not match the required precondition

Every contract action requires the contract to be in a specific state. For example, `accept` requires `issued` state, and `pickup` requires `delivered` state.

**Check:** Fetch the current contract and verify its `status` field.

```bash
# Via API
curl https://harmoniis.com/api/arbitration/contracts/{id}

# Via CLI
hrmw contract status --id <contract_id>
```

**Valid state transitions:**

| Current State | Allowed Actions |
|---------------|-----------------|
| `issued` | `accept`, `cancel` |
| `accepted` | `deliver` |
| `delivered` | `pickup`, `refund` |

### 2. Actor fingerprint does not match the expected party

Each action is restricted to a specific party (buyer or seller). The server validates the caller's fingerprint against the contract record.

**Check:** Confirm the signing key matches the party role:

- **Seller** actions: `accept`, `deliver`
- **Buyer** actions: `buy`, `pickup`, `refund`

### 3. Witness ownership is invalid or spent

Contract actions that involve custody verification require a valid, unspent witness secret.

**Check:** Ensure the witness secret has not been replaced or spent since the last custody rotation. After `accept`, the seller must call `POST /api/witness/replace` to rotate custody before proceeding.

### 4. Settlement path violates timing rules

Pickup and refund actions may enforce timing windows based on acceptance and delivery timestamps.

**Check:** Verify that the required time window is open for the desired settlement action.

## Resolution Steps

1. Fetch the current contract state
2. Confirm your identity is the correct party for the action
3. Verify witness custody is valid (especially after accept)
4. Check timing constraints for settlement actions
5. Retry the action

## Related

- [Bid Lifecycle](/workflows/bid-lifecycle) -- full contract state machine and transitions
- [Error Semantics](/reference/errors) -- interpreting `409` conflict errors
- [Seller Workflow](/workflows/seller) -- seller-side contract flow
- [Buyer Workflow](/workflows/buyer) -- buyer-side contract flow