diff --git a/CHANGELOG b/CHANGELOG
index 1dd4b21053..5f244e02c9 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -25,6 +25,8 @@ git-annex (10.20230408) UNRELEASED; urgency=medium
   * assistant --autostop: Avoid crashing when ~/.config/git-annex/autostart
     lists a directory that it cannot chdir to.
   * Honor --force option when operating on a local git remote.
+  * Added a --json-exceptions option, which makes some exceptions be output
+    in json.
 
  -- Joey Hess <id@joeyh.name>  Sat, 08 Apr 2023 13:57:18 -0400
 
diff --git a/CmdLine/GitAnnex/Options.hs b/CmdLine/GitAnnex/Options.hs
index d5364a0a60..fde99a5392 100644
--- a/CmdLine/GitAnnex/Options.hs
+++ b/CmdLine/GitAnnex/Options.hs
@@ -445,13 +445,20 @@ jsonOptions =
 		<> help "include error messages in JSON"
 		<> hidden
 		)
+	, annexFlag (setAnnexState $ Annex.setOutput (JSONOutput jsonexceptionsoptions))
+		( long "json-exceptions"
+		<> help "include exceptions in JSON"
+		<> hidden
+		)
 	]
   where
 	stdjsonoptions = JSONOptions
 		{ jsonProgress = False
 		, jsonErrorMessages = False
+		, jsonExceptions = False
 		}
 	jsonerrormessagesoptions = stdjsonoptions { jsonErrorMessages = True }
+	jsonexceptionsoptions = stdjsonoptions { jsonExceptions = True }
 
 jsonProgressOption :: [AnnexOption]
 jsonProgressOption = 
@@ -465,6 +472,7 @@ jsonProgressOption =
 	jsonoptions = JSONOptions
 		{ jsonProgress = True
 		, jsonErrorMessages = False
+		, jsonExceptions = False
 		}
 
 -- Note that a command that adds this option should wrap its seek
diff --git a/CmdLine/Seek.hs b/CmdLine/Seek.hs
index d2815383a5..bd06f55803 100644
--- a/CmdLine/Seek.hs
+++ b/CmdLine/Seek.hs
@@ -568,9 +568,9 @@ workTreeItems' (AllowHidden allowhidden) ww ps = case ww of
 			let p' = toRawFilePath p
 			relf <- liftIO $ relPathCwdToFile p'
 			ifM (not <$> (exists p' <||> hidden currbranch relf))
-				( prob (QuotedPath (toRawFilePath p) <> " not found")
+				( prob FileNotFound (QuotedPath (toRawFilePath p) <> " not found")
 				, ifM (viasymlink stopattop (upFrom relf))
-					( prob (QuotedPath (toRawFilePath p) <> " is beyond a symbolic link")
+					( prob FileBeyondSymbolicLink (QuotedPath (toRawFilePath p) <> " is beyond a symbolic link")
 					, return True
 					)
 				)
@@ -605,8 +605,8 @@ workTreeItems' (AllowHidden allowhidden) ww ps = case ww of
 			<$> catObjectMetaDataHidden f currbranch
 		| otherwise = return False
 
-	prob msg = do
-		toplevelWarning False msg
+	prob eid msg = do
+		showException False eid msg
 		Annex.incError
 		return False
 	
diff --git a/Messages.hs b/Messages.hs
index 565822365c..53d0587197 100644
--- a/Messages.hs
+++ b/Messages.hs
@@ -27,6 +27,8 @@ module Messages (
 	showEndFail,
 	showEndResult,
 	endResult,
+	ExceptionId(..),
+	showException,
 	toplevelWarning,
 	warning,
 	earlyWarning,
@@ -197,6 +199,26 @@ endResult :: Bool -> S.ByteString
 endResult True = "ok"
 endResult False = "failed"
 
+{- Unique ids for different exceptions. Do not change the constructors. -}
+data ExceptionId
+	= FileNotFound
+	| FileBeyondSymbolicLink
+	deriving (Show)
+
+{- Displays an message that is not associated with any file being
+ - processed. -}
+showException :: Bool -> ExceptionId -> StringContainingQuotedPath -> Annex ()
+showException makeway eid msg = do
+	when makeway $
+		outputMessage JSON.none id "\n"
+	outputException (show eid) (mentionedfile msg)
+		("git-annex: " <> msg <> "\n")
+  where
+	mentionedfile (QuotedPath p) = Just p
+	mentionedfile (a :+: b) = mentionedfile a <|> mentionedfile b
+	mentionedfile (UnquotedString _) = Nothing
+	mentionedfile (UnquotedByteString _) = Nothing
+
 toplevelWarning :: Bool -> StringContainingQuotedPath -> Annex ()
 toplevelWarning makeway s = warning' makeway id ("git-annex: " <> s)
 
diff --git a/Messages/Internal.hs b/Messages/Internal.hs
index a16c7d2c61..6600b98a17 100644
--- a/Messages/Internal.hs
+++ b/Messages/Internal.hs
@@ -90,11 +90,14 @@ outputError consolewhitespacef msg = withMessageState $ \s -> case (outputType s
 		qp <- coreQuotePath <$> Annex.getGitConfig
 		liftIO $ outputSerialized h $ OutputError $ decodeBS $
 			consolewhitespacef $ quote qp msg
-	_
-		| concurrentOutputEnabled s -> do
-			qp <- coreQuotePath <$> Annex.getGitConfig
-			concurrentMessage s True (decodeBS $ consolewhitespacef $ quote qp msg) go
-		| otherwise -> go
+	_ -> outputError' consolewhitespacef msg s
+
+outputError' :: (S.ByteString -> S.ByteString) -> StringContainingQuotedPath -> MessageState -> Annex ()
+outputError' consolewhitespacef msg s
+	| concurrentOutputEnabled s = do
+		qp <- coreQuotePath <$> Annex.getGitConfig
+		concurrentMessage s True (decodeBS $ consolewhitespacef $ quote qp msg) go
+	| otherwise = go
   where
 	go = do
 		qp <- coreQuotePath <$> Annex.getGitConfig
@@ -102,6 +105,17 @@ outputError consolewhitespacef msg = withMessageState $ \s -> case (outputType s
 		liftIO $ S.hPutStr stderr (consolewhitespacef $ quote qp msg)
 		liftIO $ hFlush stderr
 
+outputException :: String -> Maybe RawFilePath -> StringContainingQuotedPath -> Annex ()
+outputException eid mfile msg = withMessageState $ \s -> case outputType s of
+	(JSONOutput jsonoptions) | jsonExceptions jsonoptions ->
+		liftIO $ flushed $ JSON.emit $
+			JSON.exceptionObject eid (decodeBS (noquote msg)) mfile
+	(SerializedOutput h _) -> do
+		qp <- coreQuotePath <$> Annex.getGitConfig
+		liftIO $ outputSerialized h $ OutputException eid mfile $ decodeBS $
+			quote qp msg
+	_ -> outputError' id msg s
+
 q :: Monad m => m ()
 q = noop
 
diff --git a/Messages/JSON.hs b/Messages/JSON.hs
index 8960dd04a2..443f9b4f20 100644
--- a/Messages/JSON.hs
+++ b/Messages/JSON.hs
@@ -1,6 +1,6 @@
 {- git-annex command-line JSON output and input
  -
- - Copyright 2011-2021 Joey Hess <id@joeyh.name>
+ - Copyright 2011-2023 Joey Hess <id@joeyh.name>
  -
  - Licensed under the GNU AGPL version 3 or higher.
  -}
@@ -27,6 +27,7 @@ module Messages.JSON (
 	ObjectMap(..),
 	JSONActionItem(..),
 	AddJSONActionItemFields(..),
+	exceptionObject,
 ) where
 
 import Control.Applicative
@@ -218,3 +219,14 @@ newtype AddJSONActionItemFields a = AddJSONActionItemFields a
 
 instance ToJSON' a => ToJSON' (AddJSONActionItemFields a) where
 	toJSON' (AddJSONActionItemFields a) = object [ ("fields", toJSON' a) ]
+
+exceptionObject :: String -> String -> Maybe RawFilePath -> Object
+exceptionObject eid msg mfile = case o of
+	Object o' -> o'
+	_ -> error "internal"
+  where
+	o = object
+		[ "exception" .= toJSON' eid
+		, "message" .= toJSON' msg
+		, "file" .= toJSON' (maybe "" decodeBS mfile)
+		]
diff --git a/Messages/Serialized.hs b/Messages/Serialized.hs
index 494df5aac5..5924e10b4d 100644
--- a/Messages/Serialized.hs
+++ b/Messages/Serialized.hs
@@ -58,6 +58,9 @@ relaySerializedOutput getso sendsor meterreport runannex = go Nothing
 		Left (OutputError msg) -> do
 			runannex $ outputError id $ UnquotedString msg
 			loop st		
+		Left (OutputException eid mfile msg) -> do
+			runannex $ outputException eid mfile $ UnquotedString msg
+			loop st
 		Left (JSONObject b) -> do
 			runannex $ withMessageState $ \s -> case outputType s of
 				JSONOutput _ -> liftIO $ flushed $ JSON.emit' b
diff --git a/Types/Messages.hs b/Types/Messages.hs
index e80dc86d63..7a957a263e 100644
--- a/Types/Messages.hs
+++ b/Types/Messages.hs
@@ -9,6 +9,7 @@ module Types.Messages where
 
 import qualified Utility.Aeson as Aeson
 import Utility.Metered
+import Utility.RawFilePath
 
 import Control.Concurrent
 import System.Console.Regions (ConsoleRegion)
@@ -26,6 +27,7 @@ data OutputType
 data JSONOptions = JSONOptions
 	{ jsonProgress :: Bool
 	, jsonErrorMessages :: Bool
+	, jsonExceptions :: Bool
 	}
 	deriving (Show)
 
@@ -33,6 +35,7 @@ adjustOutputType :: OutputType -> OutputType -> OutputType
 adjustOutputType (JSONOutput old) (JSONOutput new) = JSONOutput $ JSONOptions
 	{ jsonProgress = jsonProgress old || jsonProgress new
 	, jsonErrorMessages = jsonErrorMessages old || jsonErrorMessages new
+	, jsonExceptions = jsonExceptions old || jsonExceptions new
 	}
 adjustOutputType _old new = new
 
@@ -70,6 +73,7 @@ newMessageState = do
 data SerializedOutput
 	= OutputMessage S.ByteString
 	| OutputError String
+	| OutputException String (Maybe RawFilePath) String
 	| BeginProgressMeter
 	| UpdateProgressMeterTotalSize TotalSize
 	| UpdateProgressMeter BytesProcessed
diff --git a/doc/git-annex-add.mdwn b/doc/git-annex-add.mdwn
index 7a1ad2c24e..d35d7d5a3a 100644
--- a/doc/git-annex-add.mdwn
+++ b/doc/git-annex-add.mdwn
@@ -84,7 +84,8 @@ annexed content, and other symlinks.
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to a file
+  being processed.
 
 * `--json-progress`
 
@@ -92,8 +93,13 @@ annexed content, and other symlinks.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a file.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular file.
 
 * `--batch`
 
diff --git a/doc/git-annex-addurl.mdwn b/doc/git-annex-addurl.mdwn
index 02864cebc6..3e7e0de850 100644
--- a/doc/git-annex-addurl.mdwn
+++ b/doc/git-annex-addurl.mdwn
@@ -125,7 +125,8 @@ be used to get better filenames.
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to an url
+  being processed.
 
 * `--json-progress`
 
@@ -133,8 +134,13 @@ be used to get better filenames.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing an url.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular url.
 
 * `--backend`
 
diff --git a/doc/git-annex-copy.mdwn b/doc/git-annex-copy.mdwn
index 57905b672c..9c95646076 100644
--- a/doc/git-annex-copy.mdwn
+++ b/doc/git-annex-copy.mdwn
@@ -112,11 +112,11 @@ Paths of files or directories to operate on can be specified.
 * `-z`
 
   Makes batch input be delimited by nulls instead of the usual newlines.
-
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to a file
+  being processed.
 
 * `--json-progress`
 
@@ -124,8 +124,13 @@ Paths of files or directories to operate on can be specified.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a file.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular file.
 
 * Also the [[git-annex-common-options]](1) can be used.
 
diff --git a/doc/git-annex-drop.mdwn b/doc/git-annex-drop.mdwn
index aa66696958..547cdd08f6 100644
--- a/doc/git-annex-drop.mdwn
+++ b/doc/git-annex-drop.mdwn
@@ -126,12 +126,18 @@ Paths of files or directories to drop can be specified.
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to a file
+  being processed.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a file.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular file.
 
 * Also the [[git-annex-common-options]](1) can be used.
 
diff --git a/doc/git-annex-dropkey.mdwn b/doc/git-annex-dropkey.mdwn
index 1b0ba61ac2..02a11876ac 100644
--- a/doc/git-annex-dropkey.mdwn
+++ b/doc/git-annex-dropkey.mdwn
@@ -27,12 +27,19 @@ exist; using it can easily result in data loss.
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to a key
+  being processed.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a key.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular key.
+
 
 * Also the [[git-annex-common-options]](1) can be used.
 
diff --git a/doc/git-annex-examinekey.mdwn b/doc/git-annex-examinekey.mdwn
index 4c3e1b304c..4a7ef68a45 100644
--- a/doc/git-annex-examinekey.mdwn
+++ b/doc/git-annex-examinekey.mdwn
@@ -40,12 +40,18 @@ that can be determined purely by looking at the key.
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to a key
+  being processed.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a key.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular key.
 
 * `--migrate-to-backend=backend`
 
diff --git a/doc/git-annex-export.mdwn b/doc/git-annex-export.mdwn
index 738e7fbf3c..7d781a071d 100644
--- a/doc/git-annex-export.mdwn
+++ b/doc/git-annex-export.mdwn
@@ -102,7 +102,8 @@ so the overwritten modification is not lost.)
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to a file
+  being processed.
 
 * `--json-progress`
 
@@ -110,8 +111,13 @@ so the overwritten modification is not lost.)
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a file.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular file.
 
 * Also the [[git-annex-common-options]](1) can be used.
 
diff --git a/doc/git-annex-find.mdwn b/doc/git-annex-find.mdwn
index 7a667d4672..2abcbac7b2 100644
--- a/doc/git-annex-find.mdwn
+++ b/doc/git-annex-find.mdwn
@@ -55,15 +55,19 @@ finds files in the current directory and its subdirectories.
 
 * `--json`
 
-  Output the list of files in JSON format.
-
-  This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  Enable JSON output. This is intended to be parsed by programs that use
+  git-annex. Each line of output is a JSON object corresponding to a file
+  being processed.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a file.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular file.
 
 * `--batch`
 
diff --git a/doc/git-annex-findkeys.mdwn b/doc/git-annex-findkeys.mdwn
index ac1b16d067..4e62174592 100644
--- a/doc/git-annex-findkeys.mdwn
+++ b/doc/git-annex-findkeys.mdwn
@@ -50,15 +50,19 @@ Outputs a list of keys known to git-annex.
 
 * `--json`
 
-  Output the list of keys in JSON format.
-
-  This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  Enable JSON output. This is intended to be parsed by programs that use
+  git-annex. Each line of output is a JSON object corresponding to a key
+  being processed.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a key.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular key.
 
 * Also the [[git-annex-common-options]](1) can be used.
 
diff --git a/doc/git-annex-fsck.mdwn b/doc/git-annex-fsck.mdwn
index 4083ba4bf1..a46e0d7cfd 100644
--- a/doc/git-annex-fsck.mdwn
+++ b/doc/git-annex-fsck.mdwn
@@ -103,12 +103,18 @@ better format.
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to a file
+  being processed.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a file.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular file.
 
 * `--quiet`
 
diff --git a/doc/git-annex-get.mdwn b/doc/git-annex-get.mdwn
index 208188171f..9afbdfb22a 100644
--- a/doc/git-annex-get.mdwn
+++ b/doc/git-annex-get.mdwn
@@ -126,7 +126,8 @@ be specified.
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to a file
+  being processed.
 
 * `--json-progress`
 
@@ -134,8 +135,13 @@ be specified.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a file.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular file.
 
 * Also the [[git-annex-common-options]](1) can be used.
 
diff --git a/doc/git-annex-import.mdwn b/doc/git-annex-import.mdwn
index 8d56d82270..704a903fc9 100644
--- a/doc/git-annex-import.mdwn
+++ b/doc/git-annex-import.mdwn
@@ -202,7 +202,8 @@ link, and that symbolic link will be followed.
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to a file
+  being processed.
 
 * `--json-progress`
 
@@ -210,8 +211,13 @@ link, and that symbolic link will be followed.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a file.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular file.
 
 * Also the [[git-annex-common-options]](1) can be used.
 
diff --git a/doc/git-annex-info.mdwn b/doc/git-annex-info.mdwn
index 9a2256b491..b5b7871cf8 100644
--- a/doc/git-annex-info.mdwn
+++ b/doc/git-annex-info.mdwn
@@ -24,12 +24,18 @@ for the local repository and all annexed content.
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to a item
+  being processed.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a item.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular item.
 
 * `--bytes`
 
diff --git a/doc/git-annex-lock.mdwn b/doc/git-annex-lock.mdwn
index 3e360db41c..f83171b004 100644
--- a/doc/git-annex-lock.mdwn
+++ b/doc/git-annex-lock.mdwn
@@ -26,12 +26,18 @@ can commit.
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to a file
+  being processed.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a file.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular file.
 
 * Also the [[git-annex-common-options]](1) can be used.
 
diff --git a/doc/git-annex-metadata.mdwn b/doc/git-annex-metadata.mdwn
index 9eb6ebf3aa..e8ef9dd5af 100644
--- a/doc/git-annex-metadata.mdwn
+++ b/doc/git-annex-metadata.mdwn
@@ -119,6 +119,16 @@ the modified file.
 
 	{"command":"metadata","file":"foo","key":"...","author":["bar"],...,"note":"...","success":true}
 
+* `--json-error-messages`
+
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a file.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular file.
+
 * `--json-error-messages`
 
   Messages that would normally be output to standard error are included in
diff --git a/doc/git-annex-mirror.mdwn b/doc/git-annex-mirror.mdwn
index 3dfb9aa938..546aa42c72 100644
--- a/doc/git-annex-mirror.mdwn
+++ b/doc/git-annex-mirror.mdwn
@@ -71,7 +71,8 @@ contents. Use [[git-annex-sync]](1) for that.
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to a file
+  being processed.
 
 * `--json-progress`
 
@@ -79,8 +80,13 @@ contents. Use [[git-annex-sync]](1) for that.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a file.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular file.
 
 * Also the [[git-annex-common-options]](1) can be used.
 
diff --git a/doc/git-annex-move.mdwn b/doc/git-annex-move.mdwn
index b30163c891..0d167920b2 100644
--- a/doc/git-annex-move.mdwn
+++ b/doc/git-annex-move.mdwn
@@ -111,7 +111,8 @@ Paths of files or directories to operate on can be specified.
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to a file
+  being processed.
 
 * `--json-progress`
 
@@ -119,8 +120,13 @@ Paths of files or directories to operate on can be specified.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a file.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular file.
 
 * Also the [[git-annex-common-options]](1) can be used.
 
diff --git a/doc/git-annex-registerurl.mdwn b/doc/git-annex-registerurl.mdwn
index 753d06b704..06ad999bc6 100644
--- a/doc/git-annex-registerurl.mdwn
+++ b/doc/git-annex-registerurl.mdwn
@@ -51,12 +51,19 @@ special remote that claims it. (Usually the web special remote.)
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to a key
+  being processed.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a key.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular key.
+
 
 * Also the [[git-annex-common-options]](1) can be used.
 
diff --git a/doc/git-annex-status.mdwn b/doc/git-annex-status.mdwn
index 962fda51d4..469292508c 100644
--- a/doc/git-annex-status.mdwn
+++ b/doc/git-annex-status.mdwn
@@ -24,12 +24,17 @@ modified (M), added but not committed (A), and type changed/unlocked (T).
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to a file.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a file.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular file.
 
 * Also the [[git-annex-common-options]](1) can be used.
 
diff --git a/doc/git-annex-unlock.mdwn b/doc/git-annex-unlock.mdwn
index 1a2bd32596..4fcf6d1df3 100644
--- a/doc/git-annex-unlock.mdwn
+++ b/doc/git-annex-unlock.mdwn
@@ -53,12 +53,19 @@ repository. So, enable annex.thin with care.
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to a file
+  being processed.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a file.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular file.
+
 
 * Also the [[git-annex-common-options]](1) can be used.
 
diff --git a/doc/git-annex-unregisterurl.mdwn b/doc/git-annex-unregisterurl.mdwn
index ab535a73f6..afc3f0af4d 100644
--- a/doc/git-annex-unregisterurl.mdwn
+++ b/doc/git-annex-unregisterurl.mdwn
@@ -42,12 +42,19 @@ for it, because the content may still be present on the remote.
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to a key
+  being processed.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a key.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular key.
+
 
 * Also the [[git-annex-common-options]](1) can be used.
 
diff --git a/doc/git-annex-whereis.mdwn b/doc/git-annex-whereis.mdwn
index 84678709f0..9375e0d8fb 100644
--- a/doc/git-annex-whereis.mdwn
+++ b/doc/git-annex-whereis.mdwn
@@ -71,12 +71,18 @@ received from remotes.
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  git-annex. Each line of output is a JSON object corresponding to a file
+  being processed.
 
 * `--json-error-messages`
 
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
+  Adds an "error-messages" field to the JSON that contains messages that
+  would normally be output to the standard error when processing a file.
+
+* `--json-exceptions`
+
+  Output additional JSON objects for some exceptions that are not
+  associated with a particular file.
 
 * `--format=value`
 
diff --git a/doc/todo/api_for_telling_when_nonexistant_or_non_git_files_passed/comment_3_3f0872f13160a77a82bd5a95fc3f397d._comment b/doc/todo/api_for_telling_when_nonexistant_or_non_git_files_passed/comment_3_3f0872f13160a77a82bd5a95fc3f397d._comment
index b48dd361f7..f6e1861bdd 100644
--- a/doc/todo/api_for_telling_when_nonexistant_or_non_git_files_passed/comment_3_3f0872f13160a77a82bd5a95fc3f397d._comment
+++ b/doc/todo/api_for_telling_when_nonexistant_or_non_git_files_passed/comment_3_3f0872f13160a77a82bd5a95fc3f397d._comment
@@ -31,7 +31,7 @@ bpoldrack makes a good point
 
 So eg:
 
-	{"exception":"UNIQUEID", "file":"foo", "error-messages":["foo not found"]}
+	{"exception":"UNIQUEID", "file":"foo", "message":"foo not found"}
 
 That seems about right to me, and it future proofs git-annex to be able to
 report other exceptions in json output later on.
diff --git a/doc/todo/api_for_telling_when_nonexistant_or_non_git_files_passed/comment_5_105453fbbe7361f3d409ab87079a8a41._comment b/doc/todo/api_for_telling_when_nonexistant_or_non_git_files_passed/comment_5_105453fbbe7361f3d409ab87079a8a41._comment
new file mode 100644
index 0000000000..160cf54314
--- /dev/null
+++ b/doc/todo/api_for_telling_when_nonexistant_or_non_git_files_passed/comment_5_105453fbbe7361f3d409ab87079a8a41._comment
@@ -0,0 +1,24 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 5"""
+ date="2023-04-25T18:43:20Z"
+ content="""
+I've implemented --json-exceptions:
+
+	joey@darkstar:~/tmp/xxx>git-annex add dne --json-exceptions
+	{"exception":"FileNotFound","file":"dne","message":"git-annex: dne not found\n"}
+	add: 1 failed
+
+Note that when a command like `git-annex get` is run on a file that exists,
+but is not checked into git, `git ls-files` still displays its own error message,
+so --json-exceptions doesn't help with this:
+
+	joey@darkstar:~/tmp/xxx>touch foo
+	joey@darkstar:~/tmp/xxx>git-annex get foo --json-exceptions
+	error: pathspec 'foo' did not match any file(s) known to git
+	Did you forget to 'git add'?
+	get: 1 failed
+
+Datalad will still have to parse the git output if it wants to know what file
+it failed on in that case.
+"""]]