Automatic Recovery for Stuck HMRC Submissions

Available from: v1.0.29

Overview

Occasionally an HMRC submission job can fail silently — network timeouts, transient HMRC API errors, or infrastructure interruptions can leave a quarterly submission stuck in a Submitting state indefinitely. Without intervention, the submission can never be retried and the user receives no feedback.

From v1.0.29, a scheduled Stuck Submission Rescue workflow runs every hour to detect and automatically recover these cases.

How it works

Detection

Every hour (at the top of the hour) the platform scans all quarterly summary records matching both of these conditions:

Field	Condition
`status`	equals `submitting`
`updatedAt`	more than 15 minutes ago

A record that is genuinely in-flight should update its updatedAt timestamp as the job progresses. Any record that has not been touched for 15 minutes is considered stuck.

Recovery actions

For each stuck record, the workflow performs the following steps atomically:

Updates status from submitting → failed Marks the submission as failed so that the retry UI is unlocked for the user.
Sets lastError
```
Submission timed out — the HMRC submission job did not complete. Please retry.
```
This message is surfaced in the submission detail view so the user understands what happened.
Writes an audit log entry A record is written to the auditLog entity capturing the timeout event, the affected quarterlySummary ID, and the timestamp of recovery.
Sends an in-app notification The user who originally triggered the submission receives a notification prompting them to revisit the affected quarter and retry.

What users should do

If your submission was rescued you will see an in-app notification. To retry:

Open the notification or navigate to Submissions in the main menu.
Find the affected quarterly period — it will show a Failed status.
Review the error message displayed alongside the record.
Click Retry Submission to resubmit to HMRC.

If the retry also fails, check your National Insurance Number and HMRC MTD connection under Settings → HMRC Integration before trying again.

Schedule

Property	Value
Cron expression	`0 * * * *`
Frequency	Every hour, on the hour
Timeout threshold	15 minutes in `submitting` state

Affected data

Entity	Change
`quarterlySummaries`	`status` set to `failed`; `lastError` populated
`auditLog`	New entry written per rescued submission
`notifications`	In-app notification sent to the submitting user

Frequently asked questions

Will I lose any submission data? No. The rescue workflow only updates the status and error fields. Your submission data (income, expenses, period dates) is preserved in full and will be re-sent to HMRC when you retry.

Why did my submission get stuck? Stuck submissions are typically caused by a transient HMRC API timeout or a brief infrastructure interruption. They are not caused by errors in your submission data.

How will I know if this happened to me? You will receive an in-app notification. You can also check the Audit Log under Settings for a full history of submission events.

Can this happen repeatedly? If retries continue to fail, it may indicate a persistent connectivity issue with HMRC. Contact support if you experience repeated failures.