Skip to main content
Waits for a specific log pattern to appear in a process’s stdout or stderr. This is useful for waiting until a service is ready or a specific event occurs.

​
Method Signature

await process.waitForLog(
  pattern: string | RegExp,
  timeout?: number
): Promise<WaitForLogResult>
This is a method on the Process object returned by startProcess(), not on the sandbox itself.

​
Parameters

​
pattern
string | RegExp
required
The pattern to search for in process output. Can be:
  • A string for exact substring match
  • A RegExp for pattern matching with capture groups
​
timeout
number
Maximum time to wait in milliseconds. If not specified, waits indefinitely.

​
Returns

​
WaitForLogResult
object

​
Examples

​
Wait for string in logs

const process = await sandbox.startProcess('npm run dev');

await process.waitForLog('Server running on');
console.log('Server is ready!');

​
Wait for regex pattern

const process = await sandbox.startProcess('python train.py');

const result = await process.waitForLog(/Epoch (\d+) complete/);
console.log('Matched line:', result.line);
console.log('Epoch number:', result.match?.[1]);

​
Wait with timeout

const process = await sandbox.startProcess('node server.js');

try {
  await process.waitForLog('listening on port', 10000);
  console.log('Server started successfully');
} catch (error) {
  console.error('Server did not start within 10 seconds');
}

​
Extract values from logs

const process = await sandbox.startProcess(
  'python -m http.server 8080'
);

const result = await process.waitForLog(
  /Serving HTTP on .+ port (\d+)/
);

const port = result.match?.[1];
console.log('Server started on port:', port);

​
Check multiple patterns

const process = await sandbox.startProcess('npm start');

// Wait for either success or error message
const waitSuccess = process.waitForLog('Application started');
const waitError = process.waitForLog('Error:');

const result = await Promise.race([
  waitSuccess.then(() => 'success'),
  waitError.then(() => 'error')
]);

if (result === 'success') {
  console.log('Application started successfully');
} else {
  const logs = await process.getLogs();
  console.error('Application failed to start:', logs.stderr);
}

​
Error Handling

Throws ProcessReadyTimeoutError if the timeout is reached before the pattern appears. 
import { ProcessReadyTimeoutError } from '@cloudflare/sandbox';

try {
  await process.waitForLog('ready', 5000);
} catch (error) {
  if (error instanceof ProcessReadyTimeoutError) {
    console.log('Pattern not found in logs within timeout');
    const logs = await process.getLogs();
    console.log('Current logs:', logs.stdout);
  }
}
Throws ProcessExitedBeforeReadyError if the process exits before the pattern appears. 
import { ProcessExitedBeforeReadyError } from '@cloudflare/sandbox';

try {
  await process.waitForLog('Server started');
} catch (error) {
  if (error instanceof ProcessExitedBeforeReadyError) {
    console.log('Process exited before pattern appeared');
    const logs = await process.getLogs();
    console.error('Process output:', logs.stderr);
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us