JetBrains/intellij-community · error · ConfigurationException

No external project config file is defined

Error message

No external project config file is defined

What it means

Thrown by AbstractExternalProjectImportBuilder.ensureProjectIsDefined() when getProjectFile() returns null — the import builder has no external project config file (build.gradle, pom.xml equivalent, etc.) to refresh. Before linking/previewing, the builder must resolve the external model from a config file, and with none defined it cannot proceed.

Source

Thrown at java/idea-ui/src/com/intellij/openapi/externalSystem/service/project/wizard/AbstractExternalProjectImportBuilder.java:285

  protected abstract void beforeCommit(@NotNull DataNode<ProjectData> dataNode, @NotNull Project project);

  private @Nullable File getProjectFile() {
    String path = getControl().getProjectSettings().getExternalProjectPath();
    return path == null ? null : new File(path);
  }

  /**
   * Asks current builder to ensure that target external project is defined.
   *
   * @param wizardContext             current wizard context
   * @throws ConfigurationException   if external project is not defined and can't be constructed
   */
  public void ensureProjectIsDefined(@NotNull WizardContext wizardContext) throws ConfigurationException {
    final String externalSystemName = myExternalSystemId.getReadableName();
    File projectFile = getProjectFile();
    if (projectFile == null) {
      throw new ConfigurationException(JavaUiBundle.message("error.project.undefined"));
    }
    projectFile = getExternalProjectConfigToUse(projectFile);
    final Ref<ConfigurationException> error = new Ref<>();
    final ExternalProjectRefreshCallback callback = new ExternalProjectRefreshCallback() {
      @Override
      public void onSuccess(@Nullable DataNode<ProjectData> externalProject) {
        myExternalProjectNode = externalProject;
      }

      @Override
      public void onFailure(@NotNull String errorMessage, @Nullable String errorDetails) {
        if (!StringUtil.isEmpty(errorDetails)) {
          LOG.warn(errorDetails);
        }
        error.set(new ConfigurationException(
          JavaUiBundle.message("error.resolve.with.log_link", errorMessage, PathManager.getLogPath()),
          JavaUiBundle.message("error.resolve.generic")));
      }

View on GitHub (pinned to be881553f2)

Solutions

1. Enter/select the external project location (the directory or build script) in the wizard before finishing
2. In subclass code, implement/propagate setProjectFile so getProjectFile() returns the chosen config after the path step
3. Guard: if (builder.getProjectFile() == null) keep user on the path step instead of calling ensureProjectIsDefined

Example fix

// before
// user left 'Gradle project' path empty, then Finish
builder.ensureProjectIsDefined(context); // ConfigurationException: no external project config file

// after
builder.setProjectFile(new File("/home/user/demo/build.gradle"));
builder.ensureProjectIsDefined(context);

if (builder.getProjectFile() == null) {
  // keep the user on the path step; do not call ensureProjectIsDefined yet
  return;
}
builder.ensureProjectIsDefined(context);

try {
  builder.ensureProjectIsDefined(context);
} catch (ConfigurationException e) {
  // route back to the external-project path step instead of failing the wizard
}

When it happens

Trigger: Wizard flow calling ensureProjectIsDefined(wizardContext) after the linked-project path was never set (setProjectFile not called, or the path field cleared) — getProjectFile() yields null and ConfigurationException('error.project.undefined') is thrown.

Common situations: Import-from-Gradle/Maven wizard advanced with an empty location field; subclass of AbstractExternalProjectImportBuilder forgets to store the file when the path control changes; headless import where the path was not plumbed through.

Related errors

• The project is already registered
• No external project config file is defined
• ATTACH_VM_FAILED
• Module '{0}' already exist in project. Please, specify anoth
• Enter module file location

AI-assisted analysis of JetBrains/intellij-community@be881553f2 (2026-08-14). Data as JSON: /api/errors/d72e2e6c6780f85a. Report an issue: GitHub.