From b800df2674baf1f0e9c31ab3975ee4e6d7091cb5 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Tue, 27 Jan 2026 21:15:01 +0000
Subject: [PATCH] fix(output-mapping): improve error message for missing output
 mapping source files

The previous error message 'Table sources not found' was misleading as it
implied an input mapping issue rather than an output mapping issue. The new
message clearly indicates this is an output mapping error and provides
actionable guidance to the user.

Co-Authored-By: Michal Jerabek <michal.jerabek1@gmail.com>
---
 .../src/SourcesValidator/LocalSourcesValidator.php         | 7 ++++++-
 .../tests/SourceValidator/LocalSourcesValidatorTest.php    | 4 +++-
 .../tests/Writer/StorageApiLocalTableWriterTest.php        | 4 ++--
 3 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/libs/output-mapping/src/SourcesValidator/LocalSourcesValidator.php b/libs/output-mapping/src/SourcesValidator/LocalSourcesValidator.php
index 5367a054a..2e84defe8 100644
--- a/libs/output-mapping/src/SourcesValidator/LocalSourcesValidator.php
+++ b/libs/output-mapping/src/SourcesValidator/LocalSourcesValidator.php
@@ -60,7 +60,12 @@ public function validatePhysicalFilesWithConfiguration(array $dataItems, array $
             // well, we probably should care about missing write-always sources :-/
             if (!$this->isFailedJob) {
                 throw new InvalidOutputException(
-                    sprintf('Table sources not found: %s', implode(', ', $invalidSources)),
+                    sprintf(
+                        'Output mapping error: The source file %s was not found. '
+                        . 'Verify that the transformation code creates this file in the output directory, '
+                        . 'or remove the corresponding output mapping if the file is no longer needed.',
+                        implode(', ', $invalidSources),
+                    ),
                     404,
                 );
             }
diff --git a/libs/output-mapping/tests/SourceValidator/LocalSourcesValidatorTest.php b/libs/output-mapping/tests/SourceValidator/LocalSourcesValidatorTest.php
index 4af9d1b8b..2f1955468 100644
--- a/libs/output-mapping/tests/SourceValidator/LocalSourcesValidatorTest.php
+++ b/libs/output-mapping/tests/SourceValidator/LocalSourcesValidatorTest.php
@@ -33,7 +33,9 @@ public function testValidatePhysicalFilesWithManifestWithOrphanedManifest(): voi
     public function testValidatePhysicalFilesWithConfigurationWithMissingSource(): void
     {
         $this->expectException(InvalidOutputException::class);
-        $this->expectExceptionMessage('Table sources not found: "missing.source"');
+        $this->expectExceptionMessage(
+            'Output mapping error: The source file "missing.source" was not found.',
+        );
 
         $dataItems = [$this->createMock(FileItem::class)];
         $configurationSource = [$this->createConfiguredMock(
diff --git a/libs/output-mapping/tests/Writer/StorageApiLocalTableWriterTest.php b/libs/output-mapping/tests/Writer/StorageApiLocalTableWriterTest.php
index ea3bf456d..e8dddd5c5 100644
--- a/libs/output-mapping/tests/Writer/StorageApiLocalTableWriterTest.php
+++ b/libs/output-mapping/tests/Writer/StorageApiLocalTableWriterTest.php
@@ -577,7 +577,7 @@ public function testWriteTableOutputMappingMissing(): void
             ],
         ];
         $this->expectException(InvalidOutputException::class);
-        $this->expectExceptionMessage('Table sources not found: "table81.csv"');
+        $this->expectExceptionMessage('Output mapping error: The source file "table81.csv" was not found.');
         $tableQueue = $this->getTableLoader()->uploadTables(
             configuration: new OutputMappingSettings(
                 configuration: ['mapping' => $configs],
@@ -1771,7 +1771,7 @@ public function testLocalTableUploadChecksForUnusedMappingEntries(): void
         $stagingFactory = $this->getLocalStagingFactory(logger: $this->testLogger);
 
         $this->expectException(InvalidOutputException::class);
-        $this->expectExceptionMessage('Table sources not found: "unknown.csv"');
+        $this->expectExceptionMessage('Output mapping error: The source file "unknown.csv" was not found.');
         $this->getTableLoader(
             logger: $this->testLogger,
             strategyFactory: $stagingFactory,