Troubleshooting ENA

Errors here come from three different layers, and knowing which layer produced a message tells you where to fix it.

Work through them in that order. A SeqDesk pre-check failure is always cheaper to fix than an ENA rejection.

SeqDesk registration errors

These come from POST /api/admin/submissions and appear verbatim in the UI. None of them results in a call to ENA.

Authentication

Authentication failed - invalid ENA credentials means ENA returned HTTP 401. The registration route surfaces this as a 500 with that message and marks the submission ERROR.

The connection test distinguishes two cases:

• Invalid credentials - authentication failed — a hard 401.
• Authentication failed - check your password — the response body mentioned authorization but was not a 401.

Both point at the same fix: re-enter the Webin password in Administration → ENA Credentials. The password is stored encrypted, so it cannot be read back from the settings screen to check — retyping it is the only way to be sure.

A third case is not an authentication problem at all:

Invalid username format. Expected "Webin-XXXXX" (e.g., Webin-12345), got "…"

SeqDesk validates the username against ^Webin-\d+$ before making any request. Webin-12345@ebi.ac.uk, a trailing space, or your ENA login email all fail here. Saving an invalid username is rejected too, with ENA username must be in format 'Webin-XXXXX' (e.g., Webin-12345).

Anything else — ENA server returned: 5xx, a timeout, a DNS failure — is a network or ENA availability problem. Confirm the host has outbound HTTPS to ebi.ac.uk and try again.

submg pipeline errors

These come from the metadata validator and the submg runner, both of which run before anything is submitted. The run is refused; no partial submission is created.

Study-level

Per sample

The validator reports one issue per sample, naming it:

Warnings that do not stop the run

Read these before you conclude a run was clean:

• Sample X has no bins (optional, but recommended) and Sample X: has no bins. Bin submission is optional; this sample will be submitted without bins. Run MAG binning first to include bins.
• Sample X: bin file does not exist at …; this bin will be skipped. — the sample is submitted with the remaining bins.
• Sample X: no usable bin files were found on disk. Bin submission will be skipped for this sample.
• Sample X: assembly coverage value not provided; using default 1. Set coverage_depth (or assemblyCoverageValue pipeline config) to override. — this ships a coverage of 1 to ENA. Almost always worth fixing.
• Sample X: read … FASTQ R1 path … was not found; using … instead. — a near-miss path was substituted. Verify it is the file you meant.

Runtime failures

Errors that come back from ENA

These are ENA’s words, not SeqDesk’s. They arrive inside the receipt XML, which is stored in the submission’s response JSON and rendered in the step timeline.

Taxonomy rejected

Typically “Taxon is not submittable” or a complaint about TAXON_ID. ENA does not accept every node in the NCBI taxonomy for submission — internal ranks and some unclassified nodes are not submittable.

Verify the ID at NCBI Taxonomy  and prefer the organism autocomplete over typing an ID by hand. For metagenomes, use a metagenome taxon (408170 for human gut metagenome), not the host species.

Mandatory checklist field missing

ENA validates each sample against the checklist named in its ENA-CHECKLIST attribute. If a required field is missing, check three things in order:

1. Is the value actually stored on the sample?
2. Is the key one SeqDesk maps to ENA’s name? See the field-name mapping — an unmapped key ships under its literal name and does not satisfy the checklist.
3. Is the study’s checklist type the one you intended?

The generated XML in the dashboard settles all three in one look.

Duplicate alias

ENA reports that an alias already exists in the submission account. Aliases are unique per Webin account, and unexpired test submissions occupy the namespace too.

Change the alias, or wait out the 24-hour test expiry, or check the Webin portal for the existing record. Remember the study alias defaults to the study’s internal id when none is set, so two studies never collide by accident — but re-running a registration whose accession SeqDesk failed to record will collide with itself.

Reading a failed submission

Expand the row in the Submissions Dashboard:

• Registration Steps — the timeline. The first step with an error status tells you how far the attempt got. A failure at Send Study to ENA means no samples were attempted at all; a failure at Send Samples to ENA means the project was created and you are in PARTIAL.
• Generated XML — exactly what was sent, including the merged sample attributes.
• Accession Numbers — what came back, with deep links into the ENA browser (the test browser for test submissions).

There is no separate receipt column in the database. The receipt XML lives inside the response JSON under receipt, which holds studyReceiptXml and samplesReceiptXml separately.

Recovering from a partial registration

PARTIAL means the study registered but at least one sample did not. This is the normal outcome when a single sample has bad metadata.

1. Read the sample-level errors in the step details.
2. Fix the offending samples.
3. Retry Submission on the dashboard, or register again from the study.

The re-run reuses the existing study accession, skips the samples that already have one, and submits only the remainder. Do not delete a production submission to “start clean” — that will not remove the record from ENA and will lose your audit trail.

Cleaning up test submissions

Test rows do not expire themselves in SeqDesk; only ENA forgets them. Filter the dashboard for rows whose countdown reads Expired and delete them.

Deleting a test study submission also clears studyAccessionId, submitted, submittedAt and testRegisteredAt on the study, and the matching sampleAccessionNumber on its samples — which is exactly what you want before a fresh test cycle, and exactly what you do not want on a production row. Deleting a production submission removes the audit record and leaves the accessions in place.

When none of this helps

Collect the submission id, the step timeline, the generated XML, and for submg the run folder’s logs/pipeline.err — then see Support & Messages for what a good report contains.