diff --git a/doc/generic/pgf/pgfmanual-en-base-images.tex b/doc/generic/pgf/pgfmanual-en-base-images.tex
index d5ea0b5d2..9f88b39d2 100644
--- a/doc/generic/pgf/pgfmanual-en-base-images.tex
+++ b/doc/generic/pgf/pgfmanual-en-base-images.tex
@@ -141,9 +141,9 @@ \subsection{Using an Image}
     %
 \begin{codeexample}[]
 \pgfdeclareimage[interpolate=true,width=1cm,height=1cm]
-  {image1}{brave-gnu-world-logo}
-\pgfdeclareimage[interpolate=true,width=1cm]{image2}{brave-gnu-world-logo}
-\pgfdeclareimage[interpolate=true,height=1cm]{image3}{brave-gnu-world-logo}
+  {image1}{images/brave-gnu-world-logo}
+\pgfdeclareimage[interpolate=true,width=1cm]{image2}{images/brave-gnu-world-logo}
+\pgfdeclareimage[interpolate=true,height=1cm]{image3}{images/brave-gnu-world-logo}
 \begin{pgfpicture}
   \pgftext[at=\pgfpoint{1cm}{5cm},left,base]{\pgfuseimage{image1}}
   \pgftext[at=\pgfpoint{1cm}{3cm},left,base]{\pgfuseimage{image2}}
diff --git a/tex/generic/pgf/basiclayer/pgfcoreimage.code.tex b/tex/generic/pgf/basiclayer/pgfcoreimage.code.tex
index fd1c0c48d..081fed691 100644
--- a/tex/generic/pgf/basiclayer/pgfcoreimage.code.tex
+++ b/tex/generic/pgf/basiclayer/pgfcoreimage.code.tex
@@ -35,23 +35,31 @@
   \gdef\pgf@filename{}%
   % If page= parameter is not empty, try that file first:
   \ifx\pgf@imagepage\pgfutil@empty%
+  % \pgfdebug{line 38}% **
   \else%
+  \pgfdebug{line 40: "\pgfsys@imagesuffixlist:+{#3.page\pgf@imagepage}"}%
   \expandafter\pgf@findfile\pgfsys@imagesuffixlist:+{#3.page\pgf@imagepage}%
   \fi%
+  % \pgfdebug{line 43}% **
   \ifx\pgf@filename\pgfutil@empty%
+    % \pgfdebug{line 45 finding file ...}% **
     \expandafter\pgf@findfile\pgfsys@imagesuffixlist:+{#3}%
   \else%
+    \pgfdebug{line 48}%
     \pgfkeys{/pgf/images/page=}% make page empty
   \fi%
   \ifx\pgf@filename\pgfutil@empty%
     \pgfwarning%
-    {File "#3" not found when defining image "#2".
+    {(line 53) File "#3" not found when defining image "#2".
       Tried all extensions in "\pgfsys@imagesuffixlist"}%
     \pgf@declaredraftimage{#2}{#3}%
   \else%
+    % \pgfdebug{line 57 found image ...}%
     \ifpgf@draftmode%
+      \pgfdebug{line 59 draft image ...}%
       \pgf@declaredraftimage{#2}{#3}%
     \else%
+      % \pgfdebug{line 62 image ...}%
       \pgfsys@defineimage%
     \fi%
   \fi%
@@ -82,6 +90,7 @@
 
 
 \def\pgf@findfile#1:#2+#3{%
+  % \pgfdebug{line 93/pgf@findfile: 1="#1", 2="#2", 3="#3}%
   \pgfutil@IfFileExists{#3#1}%
   {\xdef\pgf@filename{#3#1}}%
   {\def\pgf@mightbeempty{#2}%
@@ -181,23 +190,52 @@
 % \pgfputat{\pgforigin}{\pgfbox[left,base]{\pgfuseimage{myimage}}}
 
 \def\pgfuseimage#1{%
+  \pgfdebug{line 193/pgfuseimage 1="#1"}%
   \def\pgf@imagename{pgf@image@#1}%
   \pgf@tryextensions{\pgf@imagename}{\pgfalternateextension}%
+  % \pgfdebug{line 196, pgfalternateextension param: "\pgfalternateextension"}%
   \expandafter\pgfutil@ifundefined\expandafter{\pgf@imagename}%
   {\pgferror{Undefined image "#1"}}%
   {{\leavevmode\csname\pgf@imagename\endcsname}}}
 
 \def\pgf@tryextensions#1#2{%
-  \edef\pgf@args{[#2!]}\expandafter\pgf@@tryextensions\pgf@args{#1}}
+  \pgfdebug{line 202/pgf@tryextensions: 1="#1", 2="#2"}%
+  \edef\pgf@args{[#2!]}\expandafter\pgf@@tryextensions\pgf@args{#1}%
+  \pgfdebug{line 204/pgf@tryextensions: pgf@args="\pgf@args"}%
+}
+
 \def\pgf@@tryextensions[#1!#2]#3{%
+  \pgfdebug{============== 1="#1", 2="#2", 3="#3"}%
   \expandafter\pgfutil@ifundefined\expandafter{#3#1!#2}%
-  {\def\pgf@temp{#2}%
+  {%
+    \def\pgf@temp{#2}%
     \ifx\pgf@temp\pgfutil@empty%
-    \edef#3{#3!}%
+      \edef#3{#3!}%
+      \pgfdebug{line 214/pgf@@tryextensions: finalize to 3="#3"}%
     \else%
-    \pgf@@tryextensions[#2]{#3}%
-    \fi}%
-  {\edef#3{#3#1!#2}}}
+      \edef\foo{#3}%
+      \edef\bar{#3!}%
+      \pgfdebug{line 216/pgf@@tryextensions: trying with "[#1!]{#3}", foo="\foo", bar="\bar"}%
+      \pgf@@tryextensions[#1!]{#3}%
+      \pgfdebug{line 220/pgf@@tryextensions: 3="#3", foo="\foo", bar="\bar"}%
+      \edef\baz{#3}%
+      \newlength{\lenbar}\settowidth{\lenbar}{\bar}
+      \newlength{\lenbaz}\settowidth{\lenbaz}{\baz}
+      \ifdim\lenbar=\lenbaz%
+        % https://tex.stackexchange.com/questions/451/when-to-use-edef-noexpand-and-expandafter
+        \edef#3{\csname foo\endcsname}%
+        \pgfdebug{line 226/pgf@@tryextensions: trying with "[#2]{#3}"}%
+        \pgf@@tryextensions[#2]{#3}%
+      \else%
+        \pgfdebug{line 229/pgf@@tryextensions: (foo="\foo") different bar="\bar", baz="\baz"}%
+      \fi%
+    \fi%
+  }%
+  {%
+    \pgfdebug{line 221/pgf@@tryextensions: 3:"#3", 1:"#1", 2:"#2"}%
+    \edef#3{#3#1!#2}%
+    \pgfdebug{line 223/pgf@@tryextensions: finalize to "#3"}%
+  }}%
 
 
 % Alternate image
diff --git a/tex/generic/pgf/utilities/pgfutil-common.tex b/tex/generic/pgf/utilities/pgfutil-common.tex
index 39ab1c9fd..7ddae9269 100644
--- a/tex/generic/pgf/utilities/pgfutil-common.tex
+++ b/tex/generic/pgf/utilities/pgfutil-common.tex
@@ -98,7 +98,9 @@
 %
 % This macro is expandable.
 \def\pgfutil@ifundefined#1{%
-  \expandafter\pgfutil@ifx\csname#1\endcsname\relax}
+  \pgfdebug{line 101/pgfutil@ifundefined: checking if undefined: "#1"}%
+  \expandafter\pgfutil@ifx\csname#1\endcsname\relax%
+}
 
 % A variant of \pgfutil@ifundefined which will NOT let #1 to \relax it
 % is undefined.
@@ -332,6 +334,8 @@
 \def\pgferror#1{\pgfutil@packageerror{pgf}{#1}{}}
 \def\pgfwarning#1{\pgfutil@packagewarning{pgf}{#1}}
 
+\def\pgfutil@packagedebug#1#2{\immediate\write17{[DEBUG]: #2}}
+\def\pgfdebug#1{\pgfutil@packagedebug{pgf}{#1}}
 
 % Library files inclusion