diff --git a/src/main/engine/PageRenderer.ts b/src/main/engine/PageRenderer.ts
index 6800157..b697bd1 100644
--- a/src/main/engine/PageRenderer.ts
+++ b/src/main/engine/PageRenderer.ts
@@ -859,7 +859,8 @@ export async function replaceAllMacrosAsync(
   if (hasUnknownMacros && pythonMacroRenderer) {
     try {
       pythonScripts = await pythonMacroRenderer.getEnabledMacroScripts();
-    } catch {
+    } catch (error) {
+      console.warn('[PageRenderer] Failed to resolve Python macro scripts:', error instanceof Error ? error.message : String(error));
       pythonScripts = [];
     }
   }
@@ -892,7 +893,7 @@ export async function replaceAllMacrosAsync(
             hook: m.name,
             source: { kind: 'macro', id: pythonScript.id },
           },
-          params: params as Record<string, unknown>,
+          params: params,
         };
 
         const result = await pythonMacroRenderer.renderMacro({
@@ -904,7 +905,8 @@ export async function replaceAllMacrosAsync(
         });
 
         rendered.push(result.html);
-      } catch {
+      } catch (error) {
+        console.warn(`[PageRenderer] Python macro '${m.name}' failed:`, error instanceof Error ? error.message : String(error));
         rendered.push('');
       }
     } else {
diff --git a/src/renderer/macros/registry.ts b/src/renderer/macros/registry.ts
index 98a0ea4..ee50c98 100644
--- a/src/renderer/macros/registry.ts
+++ b/src/renderer/macros/registry.ts
@@ -183,8 +183,9 @@ export async function renderMacro(
       if (pythonInfo) {
         return await pythonMacroRendererFn(pythonInfo, macro.params, context);
       }
-    } catch {
-      return `<span class="macro-error" title="Python macro error">${macro.rawText}</span>`;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Python macro error';
+      return `<span class="macro-error" title="${errorMessage}">${macro.rawText}</span>`;
     }
   }
 
diff --git a/tests/renderer/macros/pythonMacroCoexistence.test.ts b/tests/renderer/macros/pythonMacroCoexistence.test.ts
index 2f3c19d..3e1919b 100644
--- a/tests/renderer/macros/pythonMacroCoexistence.test.ts
+++ b/tests/renderer/macros/pythonMacroCoexistence.test.ts
@@ -119,7 +119,7 @@ describe('Python macro coexistence in renderer registry', () => {
 
       const result = await renderMacro(macro, context);
       expect(result).toContain('macro-error');
-      expect(result).toContain('Python macro error');
+      expect(result).toContain('Resolution failed');
     });
 
     it('should show unknown macro error when no Python resolver is set', async () => {