set_exception_breakpoint

Set breakpoints to pause PHP debugging when specific exceptions occur, enabling targeted error investigation during development.

Instructions

Set a breakpoint that triggers when a specific exception is thrown. Can be set before a debug session starts.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`exception`	No	Exception class name to break on (use '*' for all exceptions, or specific like 'RuntimeException')	*
`session_id`	No	Session ID

Implementation Reference

src/tools/breakpoints.ts:149-216 (handler)

MCP tool handler for 'set_exception_breakpoint'. Handles input parameters, resolves or creates pending session breakpoint, calls underlying session.setExceptionBreakpoint if session active, and returns JSON-formatted response with success status and breakpoint details.

async ({ exception, session_id }) => {
  const session = sessionManager.resolveSession(session_id);

  // If no active session, store as pending breakpoint
  if (!session) {
    const pendingBp = pendingBreakpoints.addExceptionBreakpoint(exception);

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            {
              success: true,
              pending: true,
              message: 'Exception breakpoint stored as pending - will be applied when a debug session connects',
              breakpoint: {
                id: pendingBp.id,
                type: 'exception',
                exception,
                enabled: pendingBp.enabled,
              },
            },
            null,
            2
          ),
        },
      ],
    };
  }

  try {
    const breakpoint = await session.setExceptionBreakpoint(exception);

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            {
              success: true,
              breakpoint: {
                id: breakpoint.id,
                type: 'exception',
                exception,
                state: breakpoint.state,
              },
            },
            null,
            2
          ),
        },
      ],
    };
  } catch (error) {
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            error: 'Failed to set exception breakpoint',
            message: error instanceof Error ? error.message : String(error),
          }),
        },
      ],
    };
  }
}

src/tools/breakpoints.ts:140-148 (schema)

Zod input schema defining parameters for the tool: 'exception' (string, default '*') and optional 'session_id'.

{
  exception: z
    .string()
    .default('*')
    .describe(
      "Exception class name to break on (use '*' for all exceptions, or specific like 'RuntimeException')"
    ),
  session_id: z.string().optional().describe('Session ID'),
},

src/tools/breakpoints.ts:137-217 (registration)

Registration of the 'set_exception_breakpoint' tool using server.tool() within registerBreakpointTools function, including name, description, schema, and handler.

server.tool(
  'set_exception_breakpoint',
  'Set a breakpoint that triggers when a specific exception is thrown. Can be set before a debug session starts.',
  {
    exception: z
      .string()
      .default('*')
      .describe(
        "Exception class name to break on (use '*' for all exceptions, or specific like 'RuntimeException')"
      ),
    session_id: z.string().optional().describe('Session ID'),
  },
  async ({ exception, session_id }) => {
    const session = sessionManager.resolveSession(session_id);

    // If no active session, store as pending breakpoint
    if (!session) {
      const pendingBp = pendingBreakpoints.addExceptionBreakpoint(exception);

      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(
              {
                success: true,
                pending: true,
                message: 'Exception breakpoint stored as pending - will be applied when a debug session connects',
                breakpoint: {
                  id: pendingBp.id,
                  type: 'exception',
                  exception,
                  enabled: pendingBp.enabled,
                },
              },
              null,
              2
            ),
          },
        ],
      };
    }

    try {
      const breakpoint = await session.setExceptionBreakpoint(exception);

      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(
              {
                success: true,
                breakpoint: {
                  id: breakpoint.id,
                  type: 'exception',
                  exception,
                  state: breakpoint.state,
                },
              },
              null,
              2
            ),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              error: 'Failed to set exception breakpoint',
              message: error instanceof Error ? error.message : String(error),
            }),
          },
        ],
      };
    }
  }
);

src/session/session.ts:184-205 (helper)

Core helper method in DebugSession class that implements the DBGP protocol command 'breakpoint_set -t exception -x <exception>', parses response, creates Breakpoint object, and stores in session breakpoints map.

async setExceptionBreakpoint(exception: string = '*'): Promise<Breakpoint> {
  const response = await this.connection.sendCommand('breakpoint_set', {
    t: 'exception',
    x: exception,
  });

  if (response.error) {
    throw new Error(`Failed to set exception breakpoint: ${response.error.message}`);
  }

  const result = this.connection.parseBreakpointSet(response);

  const breakpoint: Breakpoint = {
    id: result.id,
    type: 'exception',
    state: 'enabled',
    exception,
  };

  this.breakpoints.set(breakpoint.id, breakpoint);
  return breakpoint;
}

src/session/pending-breakpoints.ts:69-81 (helper)

Helper to create and store a pending exception breakpoint when no debug session is active; later applied to session via setExceptionBreakpoint.

addExceptionBreakpoint(exception: string = '*'): PendingBreakpoint {
  const id = `pending_${++this.breakpointIdCounter}`;
  const bp: PendingBreakpoint = {
    id,
    type: 'exception',
    exception,
    enabled: true,
    createdAt: new Date(),
  };
  this.pendingBreakpoints.set(id, bp);
  logger.info(`Pending exception breakpoint added: ${id} for ${exception}`);
  this.emit('breakpointAdded', bp);
  return bp;

src/tools/index.ts:56-56 (registration)
Top-level registration call to registerBreakpointTools within registerAllTools, which includes the set_exception_breakpoint tool.
```
registerBreakpointTools(server, ctx.sessionManager, ctx.pendingBreakpoints);
```

Xdebug MCP Server