What causes "Remote repository URL invalid" in apache/maven?

Locate the offending in pom.xml, settings.xml (mirrors, profiles) or distributionManagement and correct it

apache/maven · error · TransportProviderException

Remote repository URL invalid

Error message

Remote repository URL invalid

What it means

DefaultTransportProvider.transport creates the transport for a RemoteRepository by first parsing repository.getUrl() with new URI(...). If the URL is syntactically invalid (spaces, illegal characters such as '<', '>', '|', '"'), URISyntaxException is thrown and wrapped in TransportProviderException("Remote repository URL invalid").

Source

Thrown at impl/maven-impl/src/main/java/org/apache/maven/impl/DefaultTransportProvider.java:57

public class DefaultTransportProvider implements TransportProvider {
    private final org.eclipse.aether.spi.connector.transport.TransporterProvider transporterProvider;

    @Inject
    public DefaultTransportProvider(TransporterProvider transporterProvider) {
        this.transporterProvider = requireNonNull(transporterProvider);
    }

    @Override
    public Transport transport(Session session, RemoteRepository repository) {
        try {
            URI baseURI = new URI(repository.getUrl());
            return new DefaultTransport(
                    baseURI,
                    transporterProvider.newTransporter(
                            InternalSession.from(session).getSession(),
                            ((DefaultRemoteRepository) repository).getRepository()));
        } catch (URISyntaxException e) {
            throw new TransportProviderException("Remote repository URL invalid", e);
        } catch (NoTransporterException e) {
            throw new TransportProviderException("Unsupported remote repository", e);
        }
    }
}

View on GitHub (pinned to e4093d4e12)

Solutions

Locate the offending <url> in pom.xml, settings.xml (mirrors, profiles) or distributionManagement and correct it
Percent-encode illegal characters in the URL path (space -> %20) or configure the repository with a clean path
Add a build-time validation that new URI(url) parses for every repository you declare

Example fix

<!-- before -->
<distributionManagement>
  <repository>
    <url>https://nexus.example.com/content/repositories/my releases</url>
  </repository>
</distributionManagement>

<!-- after -->
<distributionManagement>
  <repository>
    <url>https://nexus.example.com/content/repositories/my-releases</url>
  </repository>
</distributionManagement>

Defensive patterns

Strategy: validation

Validate before calling

static URI parseRepoUrl(String url) {
    try {
        return new URI(url);
    } catch (URISyntaxException e) {
        throw new IllegalArgumentException("Malformed repository URL '" + url + "': " + e.getReason(), e);
    }
}
// validate all declared repositories at startup
for (RemoteRepository r : repos) parseRepoUrl(r.getUrl());

Try / catch

try {
    transportProvider.transport(session, repository);
} catch (TransportProviderException e) {
    if (e.getCause() instanceof URISyntaxException bad) {
        // fix the URL in pom.xml / settings.xml; index tells where it breaks
        throw new IllegalArgumentException("Fix repository URL at index " + bad.getIndex() + ": " + repository.getUrl(), e);
    }
    throw e;
}

Prevention

Percent-encode spaces (%20) and avoid illegal characters in repository URLs
Validate every <url> under repositories, mirrors, and distributionManagement with new URI(url) in a config test
Prefer copying repository URLs from the repository manager's copy-paste button, not from rendered web pages

When it happens

Trigger: transport(session, repository) with a URL containing a space ('http://nexus.example.com/my repo'), illegal punctuation, or a truncated/garbled URL copied from a browser or wiki.

Common situations: Typos in <repositories>/<distributionManagement><url> in pom.xml or settings.xml; on-prem Nexus/Artifactory repo paths with unencoded spaces; mirrorOf URLs pasted with trailing fragments or smart quotes.

Related errors

AI-assisted analysis of apache/maven@e4093d4e12 (2026-08-21). Data as JSON: /api/errors/6def9688cea858a0. Report an issue: GitHub.