Pages Troubleshooting & Common Issues
In this tutorial, you'll learn about Pages Troubleshooting & Common Issues. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.
This tutorial explains how to troubleshoot common issues in Cloudflare Pages, including build failures, deployment errors, Function runtime problems, and domain configuration issues. Serverless debugging requires understanding build logs, function logs, and HTTP response headers. The DodaTech team maintains a troubleshooting checklist that resolves 90 percent of deployment issues within minutes.
Build Failure Diagnosis
Build failures are the most common Pages issue. The build log in the Cloudflare dashboard shows exactly where the Process failed.
flowchart LR
A[Build fails] --> B{Check build log}
B --> C[Syntax error]
B --> D[Dependency issue]
B --> E[Missing output dir]
B --> F[Framework mismatch]
C --> G[Fix code and retry]
D --> H[Update package.json]
E --> I[Set correct publish dir]
F --> J[Override framework preset]
style B fill:#f90,color:#fff
Checking Build Logs
Access build logs from the Cloudflare Pages dashboard under your project and click on any deployment.
// Simulate parsing a build log for common errors
function analyzeBuildLog(logText) {
const patterns = [
{ regex: /error: (.*) is not defined/i, type: 'ReferenceError', severity: 'high' },
{ regex: /Module not found: (.*)/i, type: 'MissingDependency', severity: 'high' },
{ regex: /npm ERR! code (.*)/i, type: 'NpmError', severity: 'high' },
{ regex: /Output directory (.*) does not exist/i, type: 'MissingOutputDir', severity: 'high' },
{ regex: /Warning: (.*)/i, type: 'Warning', severity: 'low' }
];
const lines = logText.split('\n');
const issues = [];
for (const line of lines) {
for (const pattern of patterns) {
const match = line.match(pattern.regex);
if (match) {
issues.push({
type: pattern.type,
severity: pattern.severity,
message: match[0],
line: line
});
}
}
}
return issues;
}
const sampleLog = 'error: react is not defined\nnpm ERR! code ENOENT\nOutput directory dist does not exist';
console.log(JSON.stringify(analyzeBuildLog(sampleLog), null, 2));
// Expected output:
// [
// { "type": "ReferenceError", "severity": "high", "message": "error: react is not defined", "line": "error: react is not defined" },
// { "type": "NpmError", "severity": "high", "message": "npm ERR! code ENOENT", "line": "npm ERR! code ENOENT" },
// { "type": "MissingOutputDir", "severity": "high", "message": "Output directory dist does not exist", "line": "Output directory dist does not exist" }
// ]
Function Runtime Issues
Functions that work locally may fail at the edge due to environment differences.
// Debug function runtime environment
export async function onRequest(context) {
const issues = [];
// Check runtime compatibility
if (typeof crypto === 'undefined') {
issues.push('crypto module not available');
}
if (typeof Response === 'undefined') {
issues.push('Response constructor not available');
}
// Check bindings
const expectedBindings = ['DB', 'KV_STORE'];
for (const binding of expectedBindings) {
if (!context.env[binding]) {
issues.push(binding + ' binding is not configured');
}
}
// Check request properties
if (!context.request) {
issues.push('Request object is missing');
}
if (issues.length > 0) {
console.log('Runtime issues found:', issues.join(', '));
return new Response(JSON.stringify({ healthy: false, issues: issues }), {
status: 500,
headers: { 'Content-Type': 'application/json' }
});
}
return new Response(JSON.stringify({ healthy: true }), {
headers: { 'Content-Type': 'application/json' }
});
}
// Expected output when bindings are missing:
// {"healthy":false,"issues":["DB binding is not configured","KV_STORE binding is not configured"]}
Domain and SSL Issues
Custom domain configuration problems often involve DNS propagation or SSL certificate validation.
// Diagnose domain configuration
async function diagnoseDomain(domain) {
const checks = {
dnsResolved: false,
hasCloudflareIP: false,
sslValid: false,
proxied: false
};
try {
const dnsResponse = await fetch('https://cloudflare-dns.com/dns-query?name=' + domain + '&type=A',
{ headers: { 'Accept': 'application/dns-json' } }
);
const dnsData = await dnsResponse.json();
if (dnsData.Answer && dnsData.Answer.length > 0) {
checks.dnsResolved = true;
checks.hasCloudflareIP = dnsData.Answer.some(function(ans) {
return ans.data.startsWith('104.16.') || ans.data.startsWith('172.64.');
});
}
} catch (e) {
console.log('DNS check failed:', e.message);
}
try {
const sslResponse = await fetch('https://' + domain);
checks.sslValid = sslResponse.status === 200;
checks.proxied = sslResponse.headers.get('server')?.includes('cloudflare');
} catch (e) {
console.log('SSL check failed:', e.message);
}
return checks;
}
diagnoseDomain('example.com').then(function(result) {
console.log(JSON.stringify(result, null, 2));
});
// Expected output:
// {
// "dnsResolved": true,
// "hasCloudflareIP": true,
// "sslValid": true,
// "proxied": true
// }
FAQ
Practice Questions
- Where do you find the build log for a failed Pages deployment?
- What is the most common cause of the 'Output directory does not exist' error?
- Which HTTP header indicates whether a request went through the Cloudflare proxy?
Summary
Troubleshoot Cloudflare Pages by checking build logs for syntax errors, dependency issues, and output directory problems. Debug function runtime issues by inspecting environment variables and binding configurations. Diagnose domain and SSL problems by checking DNS records and proxy status. Most issues are resolved by verifying configuration settings in the Cloudflare dashboard.
Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro — security-first tools for the modern web.
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro