Common Issues

Solutions to frequently encountered problems when working with Sproogy.

Dependency Injection Issues

Bean Not Found

Error:

Exception: No bean found for type com.example.UserService

Causes:

1. Class not annotated with @Component, @Service, @Controller, or @Repository
2. Class in package not scanned
3. Typo in bean name with @Qualifier

Solutions:

// 1. Add annotation
@Service // ✅ Now scannable
public class UserService { }

// 2. Check base package
@SproogyApplication(basePackage = "com.example") // Must include your package

// 3. Fix qualifier typo
@Qualifier("userService") // ✅ Correct (lowercase first letter)

Circular Dependency

Error:

Exception: Circular dependency detected: ServiceA → ServiceB → ServiceA

Solution: Refactor to remove the cycle:

// Before (circular)
@Service
public class ServiceA {
    @Autowired private ServiceB serviceB;
}

@Service
public class ServiceB {
    @Autowired private ServiceA serviceA; // ❌ Cycle!
}

// After (extract common logic)
@Service
public class SharedService { }

@Service
public class ServiceA {
    @Autowired private SharedService shared;
}

@Service
public class ServiceB {
    @Autowired private SharedService shared; // ✅ No cycle
}

Multiple Beans of Same Type

Error:

Exception: Multiple beans found for type UserRepository

Solution: Use @Primary or @Qualifier:

@Component
@Primary // ✅ This one will be injected by default
public class MySQLUserRepository implements UserRepository { }

@Component
public class PostgresUserRepository implements UserRepository { }

// Or use @Qualifier
@Autowired
@Qualifier("mySQLUserRepository")
private UserRepository repo;

Socket Server Issues

Connection Refused

Error:

java.net.ConnectException: Connection refused

Causes:

1. Server not running
2. Wrong port
3. Firewall blocking

Solutions:

# 1. Check if server is running
netstat -an | grep 8443

# 2. Verify port in .env
echo $SOCKET_PORT  # Should match client connection port

# 3. Check firewall (Linux)
sudo ufw allow 8443/tcp

SSL Handshake Failed

Error:

javax.net.ssl.SSLHandshakeException: PKIX path building failed

Cause: Client doesn't trust server certificate

Solution:

// Ensure client truststore contains server certificate
KeyStore trustStore = KeyStore.getInstance("JKS");
trustStore.load(new FileInputStream("truststore.jks"), "password".toCharArray());

TrustManagerFactory tmf = TrustManagerFactory.getInstance("SunX509");
tmf.init(trustStore);

SSLContext context = SSLContext.getInstance("TLS");
context.init(null, tmf.getTrustManagers(), null);

Endpoint Not Found

Error:

Response: {"status": 404, "data": "Endpoint not found: /users/123"}

Causes:

1. Typo in @AppMapping pattern
2. Controller not scanned
3. Server not restarted

Solutions:

// 1. Check endpoint matches exactly
@AppMapping("/users/{id}") // ✅ Correct
// Client sends: "/users/123"

// 2. Ensure controller is annotated and in scanned package
@Controller // ✅ Must have this
public class UserController { }

// 3. Restart server after code changes

JPA Issues

Table/Column Not Found

Error:

java.sql.SQLSyntaxErrorException: Table 'sproogy_db.users' doesn't exist

Solution: Create table or use auto-generation:

# application.yml
data:
  hibernate:
    hbm2ddl.auto: "update"  # Auto-create/update tables

Production

Never use hbm2ddl.auto: update in production! Use migrations (Flyway, Liquibase).

Entity Not Managed

Error:

java.lang.IllegalArgumentException: Unknown entity: com.example.User

Cause: Entity not scanned by JPA module

Solution:

// Ensure @Entity is present
@Entity
@Table(name = "users")
public class User { }

// Ensure entity is in scanned package
@SproogyApplication(basePackage = "com.example") // Must include entity package

Transaction Not Active

Error:

org.hibernate.LazyInitializationException: could not initialize proxy - no Session

Cause: Accessing lazy-loaded field outside transaction

Solution:

// Add @Transactional to method
@Transactional
public User getUserWithPosts(Long id) {
    User user = userRepository.findById(id).orElseThrow();
    user.getPosts().size(); // Force lazy load within transaction
    return user;
}

// Or use eager fetching
@Query("SELECT u FROM User u LEFT JOIN FETCH u.posts WHERE u.id = :id")
User findByIdWithPosts(@Param("id") Long id);

Configuration Issues

Environment Variables Not Loaded

Symptom: @Env fields are null

Solution:

# 1. Ensure .env file exists in working directory
ls -la .env

# 2. Check .env format (no spaces around =)
APP_NAME=MyApp  # ✅ Correct
APP_NAME = MyApp  # ❌ Wrong

# 3. Verify working directory
pwd  # Should be project root

Configuration Value Not Found

Symptom: @Value fields are null

Solution:

// 1. Check path matches YAML structure
@Value("application.socket.format.idKey") // ✅ Correct

// application.yml:
application:
  socket:
    format:
      idKey: "id"

// 2. Ensure application.yml is in src/main/resources

Performance Issues

Slow Request Processing

Symptoms: Requests take several seconds

Diagnosis:

@Component
public class PerformanceFilter implements Filter {
    @Override
    public void doFilter(Request req, Response res, FilterChain chain) {
        long start = System.currentTimeMillis();
        chain.doFilter(req, res);
        long duration = System.currentTimeMillis() - start;
        if (duration > 1000) {
            System.err.println("SLOW REQUEST: " + req.getEndpoint() + " (" + duration + "ms)");
        }
    }
}

Common Causes:

1. N+1 query problem (use JOIN FETCH)
2. No database indexes
3. Large result sets (use pagination)
4. Slow external API calls (use caching)

Memory Leaks

Symptoms: Memory grows over time

Diagnosis:

# Monitor heap usage
jconsole  # Connect to your app

# Heap dump on OutOfMemoryError
java -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/tmp/heap.hprof -jar app.jar

Common Causes:

1. Not closing sockets/streams
2. Static collections growing unbounded
3. Circular references preventing GC

Debugging Tips

Enable Detailed Logging

# application.yml
data:
  hibernate:
    show_sql: "true"
    format_sql: "true"

// Java logging
System.setProperty("org.slf4j.simpleLogger.defaultLogLevel", "DEBUG");

Test Components in Isolation

// Unit test without Sproogy
@Test
public void testUserService() {
    UserRepository mockRepo = mock(UserRepository.class);
    UserService service = new UserService(mockRepo); // Direct instantiation

    service.createUser("alice", "alice@example.com");

    verify(mockRepo).save(any(User.class));
}

Use Breakpoints

Set breakpoints in:

• Filter doFilter() methods
• Controller methods
• Service layer methods

Get Help

Still stuck? Check:

👉 Best Practices 👉 FAQ 👉 GitHub Issues