pinpoint-apm/pinpoint · error · IllegalArgumentException

name is well known

Error message

name is well known

What it means

insertService rejects names that are statically registered as well-known services (Service.wellKnownService(name) != null). Well-known names have reserved UIDs and must not be inserted into the dynamic service registry. The check runs after the basic length precondition, inside a transactional, retryable method.

Solutions

1. Choose a different, non-reserved service name.
2. Check the name beforehand with Service.wellKnownService(name) and reject in your UI/validation layer.
3. If you genuinely need that name, use the well-known service's existing UID instead of inserting a new row.

Example fix

// before
serviceRegistryService.insertService(" pinpoint"); // well-known name
// after
if (Service.wellKnownService(name) == null) {
    serviceRegistryService.insertService(name);
}

if (Service.wellKnownService(name) != null) throw new IllegalArgumentException("well-known service name: " + name);
StringPrecondition.requireHasLength(name, "name");

try { service = serviceRegistryService.insertService(name); } catch (IllegalArgumentException e) { /* surface 'name is reserved' to user */ }

When it happens

Trigger: Calling serviceRegistryService.insertService(name) (or the REST POST endpoint that delegates to it) with a name matching a well-known service constant.

Common situations: Registering a service whose name collides with built-in Pinpoint services (e.g. names pre-seeded in Service's well-known table); importing legacy data that includes reserved names.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• agentStartTimeIndex not found
• application serviceType not found. code:, name:
• Cannot add an existing column family :
• Cannot delete reserved service:
• Cannot use reserved service name:

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/609a888aa626d7a4. Report an issue: GitHub.

Appendix: source

Thrown at service-module/src/main/java/com/navercorp/pinpoint/service/service/ServiceRegistryServiceImpl.java:37

@org.springframework.stereotype.Service
public class ServiceRegistryServiceImpl implements ServiceRegistryService {

    private final ServiceRegistryDao serviceRegistryDao;
    private final IdGenerator<ServiceUid> serviceUidGenerator;

    public ServiceRegistryServiceImpl(ServiceRegistryDao serviceRegistryDao,
                                      IdGenerator<ServiceUid> serviceUidGenerator) {
        this.serviceRegistryDao = Objects.requireNonNull(serviceRegistryDao, "serviceRegistryDao");
        this.serviceUidGenerator = Objects.requireNonNull(serviceUidGenerator, "serviceUidGenerator");
    }

    @Override
    @Transactional(rollbackFor = {Exception.class})
    @Retryable(retryFor = DuplicateKeyException.class, maxAttempts = 3)
    public Service insertService(String name) {
        StringPrecondition.requireHasLength(name, "name");
        if (Service.wellKnownService(name) != null) {
            throw new IllegalArgumentException("name is well known");
        }

        int uid = serviceUidGenerator.generate().getUid();
        try {
            serviceRegistryDao.insertService(uid, name);
        } catch (DuplicateKeyException e) {
            if (serviceRegistryDao.selectServiceByName(name) != null) {
                throw new DataIntegrityViolationException("Duplicate service name: " + name, e);
            }
            throw e;
        }

        return new Service(name, uid);
    }

    @Override
    @Transactional(readOnly = true)
    public List<String> getServiceNames() {

View on GitHub (pinned to 744c3d3075)