Skip to content

Word warnings and errors by what failed, not by the library or Java class - #49

Merged
clytras merged 2 commits into
masterfrom
feature/wording
Oct 8, 2026
Merged

clytras merged 2 commits into
masterfrom
feature/wording

Conversation

@clytras

@clytras clytras commented Oct 8, 2026 •

Copy link
Copy Markdown
Owner

Warnings

The issue codes are unchanged; only the free-text messages change.

  • CATALOG_INDEX_UNUSABLE (AccessSource): since Jackcess 5.0.3 this only appears for a damaged index, so it now reads "this database's catalog index is damaged (1 of 8 tables can't be looked up); the catalog was read by scanning it instead". The README row already described a damaged index, so it needed no change.
  • UNSUPPORTED_COLUMN_TYPE (TableReader): "this column type (COMPLEX_TYPE) can't be decoded; its raw bytes are kept".

Errors that started with a Java class name

Every error now reads error: <what>: <reason>:

Where Before After
verify --jdbc-url, can't connect (JdbcOptions) error: IOException: can't connect to <url>: <reason><advice> error: <url>: can't connect: <reason><advice>
--jdbc-driver jar missing (JdbcOptions) error: NoSuchFileException: <jar>: no such JDBC driver jar error: <jar>: no such JDBC driver jar
--jdbc-driver jar with no matching driver (JdbcOptions) error: IOException: <jar> has no JDBC driver for <url> error: <jar>: no JDBC driver in it accepts <url>
Input or verify output missing (Main.requireFile) error: NoSuchFileException: <file>: no such file error: <file>: no such file
verify --jdbc-url, reading the database fails (VerifyCommand, MySqlVerifier) error: IOException: reading the database failed: … or error: IOException: the database could not be read back: … error: <url>: reading the database failed: …
verify of a SQLite output it can't read (SqliteVerifier) error: IOException: the output could not be read back: … error: <output>: the output could not be read back: …
SQLite output fails while it is written (SqliteWriter): an SQL error, PRAGMA integrity_check, or the foreign-key check error: IOException: writing the SQLite output failed: … (and the same IOException: prefix on the other two) error: <output>: SQLite could not write it: …, error: <output>: PRAGMA integrity_check failed: …, …
A --binary files name escaping its directory (BinaryFiles, can't happen) error: IOException: the file name … error: <output>: the file name …

How it works:

  • Main.message prints a plain IOException's message as is. Our own messages now always start by naming what failed.
  • A file-system error that has a reason is also printed as is, since its message is already <file>: <reason>. One without a reason gets the reason in words for the common cases: no such file, no permission, not a folder, already exists, folder not empty.
  • OutputException.of puts a plain IOException raised while an output is built under that output's name.
  • MySqlVerifier.verify now lets the SQLException through, so VerifyCommand names the URL.
  • Other I/O errors keep their class name, because the class name is the only description they have. Non-I/O errors also keep it: those are bugs.

A damaged index found while checking relationships

Damaging the index of a relationship's parent table made convert end with error: table <name> failed: IOException: Unexpected order in index entries …. The index fails while the data is checked before writing: the relationship check looks parent keys up through it. That lookup doesn't go through RowStream, so the error wasn't a SourceException, and under --on-table-error fail TableFailure threw a plain IOException.

KeyLookup (and creating it in AccessSource.keyLookup) now wraps an IOException with SourceException.readFailed, as RowStream does. The error therefore reads like the others: error: <input>: reading table <name> failed (IOException: Unexpected order in index entries …); the file may be damaged: try Compact and Repair in Access. It is reported as TABLE_READ_FAILED with the same text. Unchecked exceptions pass through unchanged, so ParentKeys still falls back to scanning when Jackcess can't seek an index's collation.

A table that fails to be written under fail is still named after the output: error: <output>: table <name> failed: ….

  • New tests in MainTest: a missing input, an unreachable --jdbc-url, a missing --jdbc-driver, and Main.message itself.
  • AtomicOutputTest covers a plain error being put under the output's name.
  • CatalogIndexTest now pins the whole new warning text.
  • VerifyJdbcIT checks the new connection-error prefix against MySQL.
  • The unsupportedFieldsV2007 golden file is updated.
  • ConvertCommandTest.aDamagedIndexReadsLikeAnyDamagedTable damages the Customers primary-key index of the schema-fidelity fixture with a new DamagedCopy.withIndexDamaged helper. Without the fix it fails with the old error: table Customers failed: IOException: Unexpected order in index entries ….
  • SqliteTableErrorTest.aWriteFailureUnderFailNamesTheOutput covers a write failure under fail.

./mvnw -B -ntp verify and ./mvnw -B -ntp verify -Pintegration both pass.

…lass

CATALOG_INDEX_UNUSABLE and UNSUPPORTED_COLUMN_TYPE describe the database
instead of naming Jackcess; the codes are unchanged. Errors read
error: <what>: <reason> instead of starting with a Java class name.
A key lookup through a damaged index failed with a plain IOException, so
the conversion ended with error: table X failed: IOException: ... instead
of naming the input and suggesting Compact and Repair. KeyLookup now
wraps it with SourceException.readFailed, as RowStream does for rows.
@clytras
clytras merged commit 3ad8870 into master Oct 8, 2026
11 checks passed
@clytras
clytras deleted the feature/wording branch October 8, 2026 14:18
@clytras clytras mentioned this pull request Oct 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant