From cb993bc942405c0ad8daacfd51dfafe5ed249297 Mon Sep 17 00:00:00 2001
From: Andreas Jordan <anj@ordix.de>
Date: Thu, 3 Sep 2026 16:02:15 +0200
Subject: [PATCH] Copy-DbaDbTableData - Name the Query requirement in the
 parameter guard message

With Query and no Table or View the guard answered with the generic message,
which reads as if SqlInstance or Database were missing. The requirement
itself stays: the resolved SMO object supplies the source connection
context, the structure AutoCreateTable scripts, the default destination
table name and the source columns of the output object, so removing it is a
feature change, not a bug fix. Copy-DbaDbViewData splats into this function
and gets the same message for free.

Fixes #10676

(do Copy-DbaDbTableData)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 public/Copy-DbaDbTableData.ps1      |  7 ++++++-
 tests/Copy-DbaDbTableData.Tests.ps1 | 14 ++++++++++++++
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/public/Copy-DbaDbTableData.ps1 b/public/Copy-DbaDbTableData.ps1
index 3ed8b1aba75..e42efc7cc04 100644
--- a/public/Copy-DbaDbTableData.ps1
+++ b/public/Copy-DbaDbTableData.ps1
@@ -326,7 +326,12 @@ function Copy-DbaDbTableData {
 
     process {
         if ((Test-Bound -Not -ParameterName InputObject) -and ((Test-Bound -Not -ParameterName SqlInstance, Database -And) -or (Test-Bound -Not -ParameterName Table, View))) {
-            Stop-Function -Message "You must pipe in a table or specify SqlInstance, Database and [View|Table]."
+            if (Test-Bound -ParameterName Query) {
+                # Without the hint at Query the message reads as if SqlInstance or Database were missing (see #10676).
+                Stop-Function -Message "When using Query, you still have to specify SqlInstance, Database and [View|Table]. The query determines the data that is copied, but the command needs the table or view as the source object for its metadata."
+            } else {
+                Stop-Function -Message "You must pipe in a table or specify SqlInstance, Database and [View|Table]."
+            }
             return
         }
 
diff --git a/tests/Copy-DbaDbTableData.Tests.ps1 b/tests/Copy-DbaDbTableData.Tests.ps1
index cbeb260bdaa..aa65b0a358d 100644
--- a/tests/Copy-DbaDbTableData.Tests.ps1
+++ b/tests/Copy-DbaDbTableData.Tests.ps1
@@ -116,6 +116,20 @@ Describe $CommandName -Tag IntegrationTests {
             $result = Copy-DbaDbTableData -SqlInstance $TestConfig.InstanceCopy2 -Database tempdb -Table dbo.dbatoolsci_example4 -Query "SELECT TOP (1) Id FROM tempdb.dbo.dbatoolsci_example4 ORDER BY Id DESC" -DestinationTable dbatoolsci_example3 -Truncate
             $result.RowsCopied | Should -Be 1
         }
+
+        It "Points at the Query requirement when Query is used without a source table" {
+            # The generic message reads as if SqlInstance or Database were missing (#10676).
+            $splatQueryOnly = @{
+                SqlInstance      = $TestConfig.InstanceCopy2
+                Database         = "tempdb"
+                Query            = "SELECT TOP (1) Id FROM dbo.dbatoolsci_example4"
+                DestinationTable = "dbatoolsci_example3"
+                WarningAction    = "SilentlyContinue"
+            }
+            $result = Copy-DbaDbTableData @splatQueryOnly
+            $result | Should -BeNullOrEmpty
+            $WarnVar | Should -Match "When using Query"
+        }
     }
 
     Context "When testing pipeline functionality" {