apache/cordova-android · error · CordovaError

Failed to instantiate ProjectBuilder builder: ${err}

Error message

Failed to instantiate ProjectBuilder builder: ${err}

What it means

builders.getBuilder(projectPath) require()s ./ProjectBuilder and constructs it inside a try/catch; any throw during module load (missing transitive dependency, syntax error, EPERM reading a file) or from the constructor is stringified into a CordovaError. The original stack is flattened, so the message's embedded 'Error: ...' text is the real cause. This error almost always indicates a broken cordova-android installation rather than a project problem.

Source

Thrown at lib/builders/builders.js:32

    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
*/

const CordovaError = require('cordova-common').CordovaError;

/**
 * Helper method that instantiates and returns a builder for specified build type.
 *
 * @return {Builder} A builder instance for specified build type.
 */
module.exports.getBuilder = function (projectPath) {
    try {
        const Builder = require('./ProjectBuilder');
        return new Builder(projectPath);
    } catch (err) {
        throw new CordovaError('Failed to instantiate ProjectBuilder builder: ' + err);
    }
};

View on GitHub (pinned to 7c1e190064)

Solutions

1. Read the embedded inner error text after 'builder: ' - it names the actual failure (e.g. Cannot find module 'X').
2. Reinstall dependencies cleanly: rm -rf node_modules package-lock.json && npm install (or npm ci).
3. Regenerate the platform: `cordova platform rm android && cordova platform add android`.
4. Check version compatibility between the cordova CLI and cordova-android platform (package.json / cordova -v).

Example fix

# before
$ cordova build android
Failed to instantiate ProjectBuilder builder: Error: Cannot find module 'lodash'

# after
$ rm -rf node_modules package-lock.json && npm install
$ cordova platform rm android && cordova platform add android
$ cordova build android

// Preflight: load the builder module the same way getBuilder does
try {
  require.resolve('cordova-android/lib/builders/ProjectBuilder');
} catch (e) {
  throw new Error('cordova-android install is broken - run npm ci / reinstall the platform: ' + e.message);
}

try {
  const builder = builders.getBuilder(projectPath);
} catch (e) {
  if (/Failed to instantiate ProjectBuilder/.test(e.message)) {
    const inner = /Error: (.*)/.exec(e.message)?.[1] || e.message;
    throw new Error(`Broken cordova-android install (${inner}) - rm -rf node_modules && npm ci, then re-add the platform`);
  }
  throw e;
}

When it happens

Trigger: Any build/run (`cordova build android`, Api.build) on an install where require('./ProjectBuilder') or `new Builder(projectPath)` throws - corrupted node_modules after an interrupted npm install, version-skew between cordova-android and cordova-common, or file munging by antivirus/lockers on Windows.

Common situations: Interrupted or partial npm install; mixing globally installed cordova with a locally pinned cordova-android; upgrading cordova without upgrading the platform; antivirus quarantining files.

AI-assisted analysis of apache/cordova-android@7c1e190064 (2026-08-22). Data as JSON: /api/errors/928085edcab0fc36. Report an issue: GitHub.