TASK-P1-004: Implement standardized exception hierarchy with error codes by Copilot · Pull Request #2902 · ArcadeData/arcadedb

Copilot · 2025-12-07T15:15:06Z

What does this PR do?

Implements a standardized exception hierarchy with error codes, diagnostic context, and JSON serialization for ArcadeDB's 46 existing exception types.

Core Components:

ErrorCode enum: 45 codes across 6 categories (Database 1xxx, Transaction 2xxx, Query 3xxx, Security 4xxx, I/O 5xxx, Network 6xxx)
Enhanced ArcadeDBException: Adds ErrorCode field, diagnostic context map, and JSON serialization while maintaining backward compatibility
ExceptionBuilder: Fluent builder pattern for exception creation with formatted messages and context

Example Usage:

// Backward compatible - existing code unchanged
throw new ArcadeDBException("Database not found");

// With error code and context (recommended)
throw ExceptionBuilder.create()
    .errorCode(ErrorCode.DATABASE_NOT_FOUND)
    .message("Database '%s' not found", dbName)
    .addContext("databaseName", dbName)
    .addContext("path", searchPath)
    .build();

// JSON serialization for APIs
catch (ArcadeDBException e) {
    return Response.status(500).entity(e.toJSON()).build();
}
// {"errorCode":1001,"errorName":"DATABASE_NOT_FOUND","category":"Database",
//  "message":"...","context":{"databaseName":"mydb"}}

Motivation

ArcadeDB's 46 exception classes lack standardization, making programmatic error handling difficult, diagnostics limited, and API error responses inconsistent.

Related issues

TASK-P1-004: Design Exception Hierarchy

Additional Notes

Implementation Details:

Zero breaking changes - all existing constructors preserved
Context map returns immutable view to callers
JSON escaping handles common cases (backslash, quotes, newlines, tabs, backspace, form-feed)
ExceptionBuilder null-safe for error codes and context keys

Documentation:

docs/architecture/ADR-001-exception-handling.md - Architecture Decision Record
docs/architecture/exception-hierarchy.md - Visual hierarchy and error code mappings
docs/architecture/IMPLEMENTATION-SUMMARY.md - Implementation details and migration path

Testing:

33 unit tests covering error codes, backward compatibility, context management, JSON serialization, builder pattern, and edge cases

Checklist

I have run the build using mvn clean package command
My unit tests cover both failure and success scenarios

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

repository.apache.org
- Triggering command: /usr/lib/jvm/temurin-21-jdk-amd64/bin/java /usr/lib/jvm/temurin-21-jdk-amd64/bin/java --enable-native-access=ALL-UNNAMED -classpath /usr/share/apache-maven-3.9.11/boot/plexus-classworlds-2.9.0.jar -Dclassworlds.conf=/usr/share/apache-maven-3.9.11/bin/m2.conf -Dmaven.home=/usr/share/apache-maven-3.9.11 -Dlibrary.jansi.path=/usr/share/apache-maven-3.9.11/lib/jansi-native -Dmaven.multiModuleProjectDirectory=/home/REDACTED/work/arcadedb/arcadedb org.codehaus.plexus.classworlds.launcher.Launcher clean compile -DskipTests (dns block)
- Triggering command: /usr/lib/jvm/temurin-21-jdk-amd64/bin/java /usr/lib/jvm/temurin-21-jdk-amd64/bin/java --enable-native-access=ALL-UNNAMED -classpath /usr/share/apache-maven-3.9.11/boot/plexus-classworlds-2.9.0.jar -Dclassworlds.conf=/usr/share/apache-maven-3.9.11/bin/m2.conf -Dmaven.home=/usr/share/apache-maven-3.9.11 -Dlibrary.jansi.path=/usr/share/apache-maven-3.9.11/lib/jansi-native -Dmaven.multiModuleProjectDirectory=/home/REDACTED/work/arcadedb/arcadedb org.codehaus.plexus.classworlds.launcher.Launcher clean install -DskipTests (dns block)
scarf.sh
- Triggering command: /home/REDACTED/work/arcadedb/arcadedb/studio/target/node/node node ./report.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

This section details on the original issue you should resolve

<issue_title>TASK-P1-004: Design Exception Hierarchy</issue_title>
<issue_description>Priority: HIGH
Effort: 2 days
Phase: Phase 1 - Foundation
Week: 3-4 (Exception Handling)

Description

Design standardized exception hierarchy with error codes

Steps

Document current exception types (46 identified)

Design base ArcadeDBException class with:

ErrorCode enum

Context map for diagnostics

JSON serialization

Builder pattern

Define error code categories:

Database errors (1xxx)

Transaction errors (2xxx)

Query errors (3xxx)

Security errors (4xxx)

I/O errors (5xxx)

Network errors (6xxx)

Create exception hierarchy diagram

Write design document

Review with team

Files to Create

engine/src/main/java/com/arcadedb/exception/ArcadeDBException.java

engine/src/main/java/com/arcadedb/exception/ErrorCode.java

engine/src/main/java/com/arcadedb/exception/ExceptionBuilder.java

docs/architecture/ADR-001-exception-handling.md

Acceptance Criteria

Exception hierarchy designed

Error code system defined

Design document written

Team approval received</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes TASK-P1-004: Design Exception Hierarchy #2866

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

…ion, and ExceptionBuilder Co-authored-by: robfrank <413587+robfrank@users.noreply.github.com>

Co-authored-by: robfrank <413587+robfrank@users.noreply.github.com>

mergify · 2025-12-07T15:58:43Z

🧪 CI Insights

Here's what we observed from your CI run for 5ef3bbb.

🟢 All jobs passed!

But CI Insights is watching 👀

codacy-production · 2025-12-07T16:25:07Z

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
✅ -0.14%	✅ 96.86%

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (`81eb40f`)	75614	47325	62.59%
Head commit (`5ef3bbb`)	75772 (+158)	47318 (-7)	62.45% (-0.14%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#2902)	159	154	96.86%

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings Change summary preferences

… with 5 updates [skip ci] Bumps the security-critical group in /studio with 5 updates: | Package | From | To | | --- | --- | --- | | [datatables.net](https://github.com/DataTables/Dist-DataTables) | `2.3.5` | `2.3.6` | | [datatables.net-bs5](https://github.com/DataTables/Dist-DataTables-Bootstrap5) | `2.3.5` | `2.3.6` | | [datatables.net-buttons](https://github.com/DataTables/Dist-DataTables-Buttons) | `3.2.5` | `3.2.6` | | [datatables.net-buttons-bs5](https://github.com/DataTables/Dist-DataTables-Buttons-Bootstrap5) | `3.2.5` | `3.2.6` | | [sweetalert2](https://github.com/sweetalert2/sweetalert2) | `11.26.12` | `11.26.17` | Updates `datatables.net` from 2.3.5 to 2.3.6 Commits * [`c111486`](DataTables/Dist-DataTables@c111486) Sync tag release - 2.3.6 * [`d51ac35`](DataTables/Dist-DataTables@d51ac35) b10fe2c01fe4f23b89984419d769cb44ae5482b3 Release 2.3.6 * [`d7946fd`](DataTables/Dist-DataTables@d7946fd) 8ac26da4545515302a3bf4c7b5217d4508d3f4b7 Dev: Well that was disappointing. Fo... * [`1483d96`](DataTables/Dist-DataTables@1483d96) 137230d3689fa4021da4fdc2ab0bdc9a6b46e26e Dev: Make test case insensitive * [`8d551f2`](DataTables/Dist-DataTables@8d551f2) 0b56dbf0d83f2457aaa105ebd7a7de32b2d09ee3 Fix: When calculation column widths,... * [`ba1021c`](DataTables/Dist-DataTables@ba1021c) a0664009d791cea3a4c05e7f9cbc60df4c71fe88 New: `columnTitleTag` option which c... * [`7f2c13e`](DataTables/Dist-DataTables@7f2c13e) 0edfb72ce5e8dcf9307b69e31fd3bb50350091d8 Fix: Table child elements should con... * [`672684e`](DataTables/Dist-DataTables@672684e) 8eb9c48f82247932525460c6affa96d7f014be1f Fix: Encoded entities could cause co... * [`dfabbeb`](DataTables/Dist-DataTables@dfabbeb) 7ff4bc952993e6570672390cc86be7bcf09e7ec6 Fix: Improving auto column width cal... * [`38ab2b0`](DataTables/Dist-DataTables@38ab2b0) d16598760a91867a274b918c17a027eccbef1bf3 Fix: Bootstrap 5 with a `table-respo... * Additional commits viewable in [compare view](DataTables/Dist-DataTables@2.3.5...2.3.6) Updates `datatables.net-bs5` from 2.3.5 to 2.3.6 Commits * [`60c9a1a`](DataTables/Dist-DataTables-Bootstrap5@60c9a1a) Sync tag release - 2.3.6 * [`3b6b349`](DataTables/Dist-DataTables-Bootstrap5@3b6b349) b10fe2c01fe4f23b89984419d769cb44ae5482b3 Release 2.3.6 * [`63530de`](DataTables/Dist-DataTables-Bootstrap5@63530de) 8ac26da4545515302a3bf4c7b5217d4508d3f4b7 Dev: Well that was disappointing. Fo... * [`e854908`](DataTables/Dist-DataTables-Bootstrap5@e854908) 137230d3689fa4021da4fdc2ab0bdc9a6b46e26e Dev: Make test case insensitive * [`3593c71`](DataTables/Dist-DataTables-Bootstrap5@3593c71) 0b56dbf0d83f2457aaa105ebd7a7de32b2d09ee3 Fix: When calculation column widths,... * [`4a7e0ea`](DataTables/Dist-DataTables-Bootstrap5@4a7e0ea) a0664009d791cea3a4c05e7f9cbc60df4c71fe88 New: `columnTitleTag` option which c... * [`0582182`](DataTables/Dist-DataTables-Bootstrap5@0582182) 0edfb72ce5e8dcf9307b69e31fd3bb50350091d8 Fix: Table child elements should con... * [`7a6258b`](DataTables/Dist-DataTables-Bootstrap5@7a6258b) 8eb9c48f82247932525460c6affa96d7f014be1f Fix: Encoded entities could cause co... * [`ffff571`](DataTables/Dist-DataTables-Bootstrap5@ffff571) 7ff4bc952993e6570672390cc86be7bcf09e7ec6 Fix: Improving auto column width cal... * [`5163d89`](DataTables/Dist-DataTables-Bootstrap5@5163d89) d16598760a91867a274b918c17a027eccbef1bf3 Fix: Bootstrap 5 with a `table-respo... * Additional commits viewable in [compare view](DataTables/Dist-DataTables-Bootstrap5@2.3.5...2.3.6) Updates `datatables.net-buttons` from 3.2.5 to 3.2.6 Release notes *Sourced from [datatables.net-buttons's releases](https://github.com/DataTables/Dist-DataTables-Buttons/releases).* > 3.2.6 > ----- > > Buttons 3.2.6 Commits * [`69c8457`](DataTables/Dist-DataTables-Buttons@69c8457) Sync tag release - 3.2.6 * [`5b20398`](DataTables/Dist-DataTables-Buttons@5b20398) b4916a4c6f75652961cd0009eb057ed9b7f709d6 Release 3.2.6 * [`3e53554`](DataTables/Dist-DataTables-Buttons@3e53554) f77cdc03b840585c888de8408ed865948d1e55f3 Fix: Using a popover would cause all... * [`d2e27a4`](DataTables/Dist-DataTables-Buttons@d2e27a4) 60aeb97304546bdfa5cacab72b01fb2671bc80d5 Update: SCSS updates for Dart SASS c... * [`2b7438e`](DataTables/Dist-DataTables-Buttons@2b7438e) Sync tag release - 3.2.5 * [`b0efb3d`](DataTables/Dist-DataTables-Buttons@b0efb3d) 2ff898f8380790519bf30383dd381f4a72f81689 Release 3.2.5 * [`e606b03`](DataTables/Dist-DataTables-Buttons@e606b03) f8bc4cf6631141b18d3e93212218be6636fcd84d Fix: Correct return for `button().ad... * [`cd974be`](DataTables/Dist-DataTables-Buttons@cd974be) 08be23318d636f1085efdf6e43776d5a3fc3fff6 Test: Update how the sleep / wait wo... * [`9f89e4e`](DataTables/Dist-DataTables-Buttons@9f89e4e) 050771b275360ecc64fe90936598e379783e1800 Docs: `message` option is deprecated... * See full diff in [compare view](DataTables/Dist-DataTables-Buttons@3.2.5...3.2.6) Updates `datatables.net-buttons-bs5` from 3.2.5 to 3.2.6 Release notes *Sourced from [datatables.net-buttons-bs5's releases](https://github.com/DataTables/Dist-DataTables-Buttons-Bootstrap5/releases).* > 3.2.6 > ----- > > Buttons Bootstrap5 3.2.6 Commits * See full diff in [compare view](DataTables/Dist-DataTables-Buttons-Bootstrap5@3.2.5...3.2.6) Updates `sweetalert2` from 11.26.12 to 11.26.17 Release notes *Sourced from [sweetalert2's releases](https://github.com/sweetalert2/sweetalert2/releases).* > v11.26.17 > --------- > > [11.26.17](sweetalert2/sweetalert2@v11.26.16...v11.26.17) (2025-12-22) > ------------------------------------------------------------------------------------------------- > > ### Bug Fixes > > * add last strict type and enable TypeScript strict mode ([#2904](https://redirect.github.com/sweetalert2/sweetalert2/issues/2904)) ([201c0f6](sweetalert2/sweetalert2@201c0f6)) > > v11.26.16 > --------- > > [11.26.16](sweetalert2/sweetalert2@v11.26.15...v11.26.16) (2025-12-21) > ------------------------------------------------------------------------------------------------- > > ### Bug Fixes > > * strict types in 6 core files ([#2903](https://redirect.github.com/sweetalert2/sweetalert2/issues/2903)) ([330e879](sweetalert2/sweetalert2@330e879)) > > v11.26.15 > --------- > > [11.26.15](sweetalert2/sweetalert2@v11.26.14...v11.26.15) (2025-12-21) > ------------------------------------------------------------------------------------------------- > > ### Bug Fixes > > * strict types in core modules ([#2902](https://redirect.github.com/sweetalert2/sweetalert2/issues/2902)) ([a43f5f9](sweetalert2/sweetalert2@a43f5f9)) > > v11.26.14 > --------- > > [11.26.14](sweetalert2/sweetalert2@v11.26.13...v11.26.14) (2025-12-21) > ------------------------------------------------------------------------------------------------- > > ### Bug Fixes > > * strict types in DOM and template utilities ([#2901](https://redirect.github.com/sweetalert2/sweetalert2/issues/2901)) ([71167cd](sweetalert2/sweetalert2@71167cd)) > > v11.26.13 > --------- > > [11.26.13](sweetalert2/sweetalert2@v11.26.12...v11.26.13) (2025-12-21) > ------------------------------------------------------------------------------------------------- > > ### Bug Fixes > > * strict types in renderInput.js ([#2900](https://redirect.github.com/sweetalert2/sweetalert2/issues/2900)) ([0b279a3](sweetalert2/sweetalert2@0b279a3)) Changelog *Sourced from [sweetalert2's changelog](https://github.com/sweetalert2/sweetalert2/blob/main/CHANGELOG.md).* > [11.26.17](sweetalert2/sweetalert2@v11.26.16...v11.26.17) (2025-12-22) > ------------------------------------------------------------------------------------------------- > > ### Bug Fixes > > * add last strict type and enable TypeScript strict mode ([#2904](https://redirect.github.com/sweetalert2/sweetalert2/issues/2904)) ([201c0f6](sweetalert2/sweetalert2@201c0f6)) > > [11.26.16](sweetalert2/sweetalert2@v11.26.15...v11.26.16) (2025-12-21) > ------------------------------------------------------------------------------------------------- > > ### Bug Fixes > > * strict types in 6 core files ([#2903](https://redirect.github.com/sweetalert2/sweetalert2/issues/2903)) ([330e879](sweetalert2/sweetalert2@330e879)) > > [11.26.15](sweetalert2/sweetalert2@v11.26.14...v11.26.15) (2025-12-21) > ------------------------------------------------------------------------------------------------- > > ### Bug Fixes > > * strict types in core modules ([#2902](https://redirect.github.com/sweetalert2/sweetalert2/issues/2902)) ([a43f5f9](sweetalert2/sweetalert2@a43f5f9)) > > [11.26.14](sweetalert2/sweetalert2@v11.26.13...v11.26.14) (2025-12-21) > ------------------------------------------------------------------------------------------------- > > ### Bug Fixes > > * strict types in DOM and template utilities ([#2901](https://redirect.github.com/sweetalert2/sweetalert2/issues/2901)) ([71167cd](sweetalert2/sweetalert2@71167cd)) > > [11.26.13](sweetalert2/sweetalert2@v11.26.12...v11.26.13) (2025-12-21) > ------------------------------------------------------------------------------------------------- > > ### Bug Fixes > > * strict types in renderInput.js ([#2900](https://redirect.github.com/sweetalert2/sweetalert2/issues/2900)) ([0b279a3](sweetalert2/sweetalert2@0b279a3)) Commits * [`d6d3cfe`](sweetalert2/sweetalert2@d6d3cfe) chore(release): 11.26.17 [skip ci] * [`201c0f6`](sweetalert2/sweetalert2@201c0f6) fix: add last strict type and enable TypeScript strict mode ([#2904](https://redirect.github.com/sweetalert2/sweetalert2/issues/2904)) * [`5b62033`](sweetalert2/sweetalert2@5b62033) chore(release): 11.26.16 [skip ci] * [`330e879`](sweetalert2/sweetalert2@330e879) fix: strict types in 6 core files ([#2903](https://redirect.github.com/sweetalert2/sweetalert2/issues/2903)) * [`c98fc22`](sweetalert2/sweetalert2@c98fc22) chore(release): 11.26.15 [skip ci] * [`a43f5f9`](sweetalert2/sweetalert2@a43f5f9) fix: strict types in core modules ([#2902](https://redirect.github.com/sweetalert2/sweetalert2/issues/2902)) * [`31061db`](sweetalert2/sweetalert2@31061db) chore(release): 11.26.14 [skip ci] * [`71167cd`](sweetalert2/sweetalert2@71167cd) fix: strict types in DOM and template utilities ([#2901](https://redirect.github.com/sweetalert2/sweetalert2/issues/2901)) * [`4d6b29b`](sweetalert2/sweetalert2@4d6b29b) chore(release): 11.26.13 [skip ci] * [`0b279a3`](sweetalert2/sweetalert2@0b279a3) fix: strict types in renderInput.js ([#2900](https://redirect.github.com/sweetalert2/sweetalert2/issues/2900)) * See full diff in [compare view](sweetalert2/sweetalert2@v11.26.12...v11.26.17) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) --- Dependabot commands and options You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore major version` will close this group update PR and stop Dependabot creating any more for the specific dependency's major version (unless you unignore this specific dependency's major version or upgrade to it yourself) - `@dependabot ignore minor version` will close this group update PR and stop Dependabot creating any more for the specific dependency's minor version (unless you unignore this specific dependency's minor version or upgrade to it yourself) - `@dependabot ignore ` will close this group update PR and stop Dependabot creating any more for the specific dependency (unless you unignore this specific dependency or upgrade to it yourself) - `@dependabot unignore ` will remove all of the ignore conditions of the specified dependency - `@dependabot unignore ` will remove the ignore condition of the specified dependency and ignore conditions

Initial plan

42c6b77

Copilot AI assigned Copilot and robfrank Dec 7, 2025

Copilot started work on behalf of robfrank December 7, 2025 15:15 View session

Copilot AI and others added 4 commits December 7, 2025 15:23

Implement exception hierarchy with ErrorCode, enhanced ArcadeDBExcept…

8c7d851

…ion, and ExceptionBuilder Co-authored-by: robfrank <413587+robfrank@users.noreply.github.com>

Add exception hierarchy diagram and documentation

106646a

Co-authored-by: robfrank <413587+robfrank@users.noreply.github.com>

Address code review feedback: improve null safety and JSON escaping

2c69305

Co-authored-by: robfrank <413587+robfrank@users.noreply.github.com>

Add comprehensive implementation summary

644f8de

Co-authored-by: robfrank <413587+robfrank@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Design standardized exception hierarchy with error codes~~ TASK-P1-004: Implement standardized exception hierarchy with error codes Dec 7, 2025

Copilot AI requested a review from robfrank December 7, 2025 15:31

Copilot finished work on behalf of robfrank December 7, 2025 15:31

fix pre-commit

5ef3bbb

robfrank closed this Dec 17, 2025

robfrank deleted the copilot/design-exception-hierarchy branch December 17, 2025 18:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

TASK-P1-004: Implement standardized exception hierarchy with error codes#2902

TASK-P1-004: Implement standardized exception hierarchy with error codes#2902
Copilot wants to merge 6 commits intomainfrom
copilot/design-exception-hierarchy

Copilot AI commented Dec 7, 2025 •

edited

Loading

Uh oh!

mergify bot commented Dec 7, 2025 •

edited

Loading

Uh oh!

codacy-production bot commented Dec 7, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Copilot AI commented Dec 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Motivation

Related issues

Additional Notes

Checklist

I tried to connect to the following addresses, but was blocked by firewall rules:

Description

Steps

Files to Create

Acceptance Criteria

Comments on the Issue (you are @copilot in this section)

Uh oh!

mergify bot commented Dec 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🧪 CI Insights

🟢 All jobs passed!

Uh oh!

codacy-production bot commented Dec 7, 2025

Coverage summary from Codacy

See diff coverage on Codacy

See your quality gate settings Change summary preferences

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Dec 7, 2025 •

edited

Loading

mergify bot commented Dec 7, 2025 •

edited

Loading