Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
graphqlUploadExpress
✓ import graphqlUploadExpress from 'graphql-upload/graphqlUploadExpress.mjs'
✗ import { graphqlUploadExpress } from 'graphql-upload'
ESM-only since v16; uses deep imports. CommonJS require not supported.
graphqlUploadKoa
✓ import graphqlUploadKoa from 'graphql-upload/graphqlUploadKoa.mjs'
✗ import { graphqlUploadKoa } from 'graphql-upload'
ESM-only since v16; uses deep imports.
GraphQLUpload
✓ import GraphQLUpload from 'graphql-upload/GraphQLUpload.mjs'
✗ import { GraphQLUpload } from 'graphql-upload'
Default export from the module; named export only from type definitions in TypeScript.
processRequest
✓ import processRequest from 'graphql-upload/processRequest.mjs'
✗ const processRequest = require('graphql-upload/processRequest.mjs')
ESM-only deep import; no CommonJS require available.
FileUpload
✓ import type { FileUpload } from 'graphql-upload/processRequest.mjs'
✗ import { FileUpload } from 'graphql-upload'
TypeScript type import only; not a runtime export.
Express server with graphql-upload middleware handling a single file upload mutation using the Upload scalar.
import express from 'express';
import { createHandler } from 'graphql-http/lib/use/express';
import { buildSchema } from 'graphql';
import graphqlUploadExpress from 'graphql-upload/graphqlUploadExpress.mjs';
import GraphQLUpload from 'graphql-upload/GraphQLUpload.mjs';
const schema = buildSchema(`
scalar Upload
type File {
filename: String!
mimetype: String!
encoding: String!
}
type Mutation {
singleUpload(file: Upload!): File!
}
type Query {
_: Boolean
}
`);
const rootValue = {
singleUpload: async (parent, { file }) => {
const { filename, mimetype, encoding, createReadStream } = await file;
const stream = createReadStream();
// Process stream (e.g., save to disk or cloud)
// For demo, just discard the stream
stream.resume();
return { filename, mimetype, encoding };
}
};
const app = express();
app.use('/graphql', graphqlUploadExpress({ maxFileSize: 10000000, maxFiles: 10 }));
app.all('/graphql', createHandler({ schema, rootValue }));
app.listen(4000, () => console.log('Server running on port 4000'));
Errors
Common errors & fixes
Cannot find module 'graphql-upload'
Using import from the package root (e.g., import { GraphQLUpload } from 'graphql-upload') which is not exported since v14.
fixUse deep imports: import GraphQLUpload from 'graphql-upload/GraphQLUpload.mjs'
TypeError: graphqlUploadExpress is not a function
Using named import instead of default import for the middleware module.
fixUse default import: import graphqlUploadExpress from 'graphql-upload/graphqlUploadExpress.mjs'
Error: Cannot find module 'graphql-upload/GraphQLUpload.mjs'
The package version is <14.0.0 where modules were in .js files.
fixUpdate to a newer version (>=14) or use the correct extension: 'graphql-upload/GraphQLUpload.js' for older versions.
TypeError: file.createReadStream is not a function
Calling createReadStream on the file promise before awaiting it, or the promise failed.
fixAwait the file promise first: const { createReadStream } = await file; Audit
Dependencies
graphqlrequiredpeer dependency required for GraphQL scalar Upload integration
busboyrequiredprocesses multipart request bodies; security-critical dependency
fs-capacitorrequiredmanages temporary file streams and cleanup