When everything appears to work perfectly but nothing is actually happening behind the scenes, you have the most dangerous kind of bug. This is the story of how we discovered and fixed a critical issue in Vigma's documentation generation system that was silently failing for weeks.
Published: December 9, 2025
When everything appears to work perfectly but nothing is actually happening behind the scenes, you have the most dangerous kind of bug. This is the story of how we discovered and fixed a critical issue in Vigma's documentation generation system that was silently failing for weeks.
Vigma automatically generates comprehensive documentation for every project and API you create. When a user creates a new project, we generate:
Similarly, when generating APIs, we create detailed documentation with request/response schemas, usage examples, and testing instructions.
The issue? None of these files were actually being saved to the database.
The problem lived in a subtle architectural issue: server-side fetch with relative URLs.
// ❌ This fails silently on the server
const saveResponse = await fetch('/api/files', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
projectId,
files: documentationFiles,
}),
});
if (!saveResponse.ok) {
console.error('Failed to save files'); // This always executed
}
Next.js API routes run on the server-side, where the environment is fundamentally different from the browser:
/api/files work because they're relative to window.locationwindow.location exists - relative URLs cannot be resolvedfetch('/api/files') attempts to connect to an invalid URL and failsThe fetch call would fail, but our error handling made it appear as though everything worked. Users would see "✅ Generated 4 documentation files" when in reality, zero files were created.
We implemented a fundamental architectural improvement: eliminate HTTP overhead entirely.
file-save-helper.tsInstead of making HTTP calls from server-side code to other server-side code, we now save files directly to the database:
// ✅ Direct database access - no HTTP needed
import { saveFilesDirectly } from '@/lib/file-save-helper';
const result = await saveFilesDirectly(projectId, [
{
path: 'docs/README.md',
content: readmeContent,
type: 'markdown', // Auto-detected from extension
size: calculateFileSize(readmeContent),
isDraft: false,
},
// ... more files
]);
if (!result.success) {
console.error(`Failed to save: ${result.error}`);
// Now we can actually handle the error
}
.md → markdown, .ts → typescript, etc.While fixing the main issue, we discovered and resolved several related problems:
// ❌ Before: Markdown files marked as TypeScript
type: 'typescript', // Wrong!
// ✅ After: Automatic detection
type: getFileType(doc.path), // .md → 'markdown'
Our code tried to use fields that didn't exist in the Prisma schema:
// ❌ Before: Schema doesn't have these fields
await prisma.file.create({
// ...
lastModified: new Date(), // ❌ Doesn't exist
s3Url: storageUrl, // ❌ Doesn't exist
});
// ✅ After: Schema-compliant
await prisma.file.create({
// ...
// Only use fields that actually exist
});
We implemented comprehensive testing to ensure the fix works:
npm run typecheck
✓ No errors - All type issues resolved
Key Takeaway: Always use full URLs or direct function calls in server-side code. Relative URLs are for browsers only.
Key Takeaway: Silent failures are worse than loud crashes. Always ensure errors surface visibly:
// ❌ Bad: Swallows errors
try {
await riskyOperation();
} catch (error) {
console.error('Failed'); // Not enough context
}
// ✅ Good: Provides actionable information
try {
const result = await riskyOperation();
if (!result.success) {
throw new Error(`Operation failed: ${result.error}`);
}
} catch (error) {
console.error('Full context:', error);
throw error; // Let caller handle it
}
Key Takeaway: When both the caller and callee are server-side, direct function calls are superior to HTTP:
With this fix deployed, we're planning several improvements:
Currently, documentation is generated once at creation. We're working on:
Allow users to customize the documentation structure:
Enhance documentation quality with AI:
This bug taught us valuable lessons about the subtleties of server-side JavaScript and the importance of proper error visibility. What started as a seemingly minor issue - "documentation isn't showing up" - turned out to be a fundamental architectural problem affecting every project created on Vigma.
The fix not only resolved the immediate issue but also improved performance, reliability, and maintainability of our entire file management system. Most importantly, users can now trust that when Vigma says documentation was generated, it actually was.
Technical Details: Full implementation details and code examples are available in our GitHub repository. The fix is documented in docs/DOCUMENTATION_GENERATION_FIX.md.
Affected Versions: All versions prior to December 9, 2025 Fixed In: v0.2.1 and above
Written by the Vigma Engineering Team