Common Errors and Issues When Working with PFLD: A Complete Troubleshooting Guide

The most frequent errors when working with PFLD stem from TensorFlow 1.x legacy code running on TF 2.x, malformed landmark annotations expecting exactly 196 float values, and missing placeholder tensors in the inference graph.

The guoqiangqi/pfld repository implements the Progressive Face Localization Detector (PFLD) using TensorFlow 1.12–1.15. While the architecture follows the original research paper, developers often encounter common errors or issues when working with PFLD due to version incompatibilities, strict data formatting requirements, and deprecated API usage. This guide maps every major failure mode to its root cause in the source code and provides tested fixes.

TensorFlow Version Compatibility Errors

The repository was built for the TensorFlow 1.x ecosystem. Running it on TensorFlow 2.x without compatibility shims triggers a cascade of AttributeError and RuntimeError exceptions.

The Missing tensorflow.contrib Module

Symptom: AttributeError: module 'tensorflow' has no attribute 'contrib'

Root Cause: The code imports tensorflow.contrib.slim in several files to build the MobileNet-V2 backbone. In model2.py at line 6, the statement import tensorflow.contrib.slim as slim fails because the contrib submodule was removed in TensorFlow 2.x.

Fix: Add a compatibility shim at the top of every script to emulate TensorFlow 1.x behavior:

import tensorflow.compat.v1 as tf
tf.disable_v2_behavior()  # Disables eager execution and restores TF 1.x semantics

import tensorflow.contrib.slim as slim  # Now safe to import

Deprecated I/O and Image Operations

Symptom: AttributeError: module 'tensorflow' has no attribute 'read_file' or tf.image.resize_images

Root Cause: In generate_data.py at line 17, the function _parse_data calls tf.read_file and tf.image.decode_png, which moved to tf.io and tf.image namespaces in TensorFlow 2.x. Additionally, line 21 uses tf.image.resize_images, which is deprecated in favor of tf.image.resize.

Fix: Replace the legacy calls with their modern equivalents or rely on the compatibility shim above:

# Robust image loading that handles PNG or JPG

def _parse_data(filename, landmarks, attributes, euler_angles):
    raw = tf.io.read_file(filename)  # Updated API

    image = tf.image.decode_image(raw, channels=3)  # Auto-detects format

    image.set_shape([None, None, 3])
    image = tf.image.resize(image, [args.image_size, args.image_size])  # Updated API

    image = tf.cast(image, tf.float32) / 256.0
    return image, landmarks, attributes, euler_angles

Session Conflicts and Eager Execution

Symptom: RuntimeError: tf.Session() is not compatible with eager execution or AttributeError: 'Tensor' object has no attribute 'shape'

Root Cause: train_model.py at line 26 creates a tf.Session to run the static graph. In TensorFlow 2.x, eager execution is enabled by default, making tf.Session obsolete. Additionally, debug print statements in model2.py call tensor.get_shape() and then access .shape, which behaves differently in TF 2.x.

Fix: Disable eager execution at the start of train_model.py and test_model.py:

import tensorflow.compat.v1 as tf
tf.disable_v2_behavior()  # Restores TF 1.x session behavior

tf.compat.v1.disable_eager_execution()  # Explicitly disable eager mode

Data Pipeline and Annotation Format Failures

PFLD expects the WFLW dataset format: each line must contain exactly 196 floating-point landmark coordinates (98 points × 2 coordinates), plus attributes and Euler angles. Deviations cause immediate crashes.

Landmark Dimension Mismatches

Symptom: InvalidArgumentError: Input to reshape is a tensor with 0 values, but the requested shape has 196 elements

Root Cause: In generate_data.py at lines 38–40, the gen_data function parses each line of list.txt using np.asarray(..., dtype=np.float32). If a line contains fewer than 196 values (corrupted annotation or missing values), the array is shorter than expected. The landmark_batch placeholder in train_model.py expects shape (None, 196), causing a reshape failure.

Fix: Add validation when parsing the annotation file:

# In generate_data.py, after parsing landmarks

landmark = np.asarray(landmark_list, dtype=np.float32)
assert landmark.shape[0] == 196, f'Bad annotation line {i}: expected 196 values, got {landmark.shape[0]}'

Image Path and Format Issues

Symptom: FileNotFoundError or InvalidArgumentError: PNG header mismatch when loading images

Root Cause: The _parse_data function in generate_data.py assumes all images are PNG format and uses tf.image.decode_png. If the dataset contains JPEG files or if paths in list.txt are incorrect, the decoder fails.

Fix: Use the format-agnostic tf.image.decode_image as shown in the compatibility section above, or verify that all images are converted to PNG before training.

Model Architecture and Training Instabilities

Even with correct data and TensorFlow versions, the training script contains mathematical operations that can produce NaNs or memory bottlenecks.

Attribute Weighting Division by Zero

Symptom: ZeroDivisionError or NaN values in loss during training

Root Cause: In train_model.py at line 92, the code calculates attribute weights using tf.map_fn with a lambda that divides by the attribute count: 1/x. If an attribute never appears in a batch (x=0), the fallback float(args.batch_size) inserts a Python float into the TensorFlow graph, causing type mismatches and potential division-by-zero errors.

Fix: Replace the fallback with a TensorFlow constant to ensure graph consistency:

# Replace line 92 in train_model.py

mat_ratio = tf.map_fn(
    lambda x: tf.cond(
        tf.greater(x, 0.0), 
        lambda: 1.0 / x, 
        lambda: tf.cast(args.batch_size, tf.float32)  # Safe fallback

    ), 
    mat_ratio
)

Euler Angle Loss Computation Bottlenecks

Symptom: Training is extremely slow or OOM (Out of Memory) errors on large batches

Root Cause: The loss computation in train_model.py uses tf.map_fn to calculate 1 - tf.cos(abs(x)) for Euler angle differences. This creates a Python-level loop over the batch dimension, preventing GPU vectorization and causing memory leaks as noted in the repository's README.

Fix: Vectorize the operation to process the entire batch at once:

# Inside train_model.py, replace the tf.map_fn block

diff = euler_angles_gt_batch - euler_angles_pre

# Vectorized cosine loss

angle_loss = tf.reduce_sum(1.0 - tf.cos(tf.abs(diff)), axis=1)  # shape [batch]

_sum_k = tf.reduce_sum(angle_loss)  # scalar

# Continue with landmark loss...

loss_sum = tf.reduce_mean(tf.square(landmark_batch - landmarks_pre), axis=1)
final_loss = tf.reduce_mean(loss_sum * _sum_k * attributes_w_n)

Missing Placeholder Tensors in Model Inference

Symptom: ValueError: The placeholder tensor 'phase_train' does not exist or batch normalization issues during inference

Root Cause: The create_model function in model2.py expects a boolean placeholder named phase_train to control batch normalization behavior (training vs. inference). If you instantiate the model directly without passing this placeholder (e.g., when loading a checkpoint for inference), the graph construction fails because the normalizer_params reference a non-existent tensor.

Fix: Always explicitly create and pass the phase placeholder:

# When calling create_model for inference or training

phase_train = tf.placeholder(tf.bool, name='phase_train')
landmarks, loss, euler_angles = create_model(
    input_images, 
    ground_truth_landmarks, 
    phase_train, 
    args
)

# For inference, feed False to phase_train

sess.run(landmarks, feed_dict={input_images: batch, phase_train: False})

Summary

• TensorFlow Version Mismatch: The repository requires TF 1.x APIs (tf.contrib.slim, tf.Session) that are removed or changed in TF 2.x. Use tf.compat.v1 shims to restore legacy behavior.
• Strict Data Formatting: The pipeline expects exactly 196 landmark values (98 points × 2 coordinates) per annotation line. Corrupted lines or missing values cause InvalidArgumentError during reshaping.
• Graph Construction Pitfalls: The phase_train placeholder must be explicitly passed to create_model to control batch normalization, and attribute weighting requires safe division handling to prevent NaN values.
• Performance Bottlenecks: Replace the tf.map_fn loop in the Euler angle loss calculation with vectorized operations to prevent memory leaks and accelerate GPU training.

Frequently Asked Questions

Can I run PFLD with TensorFlow 2.x?

Yes, but you must disable eager execution and import the compatibility layer. Add import tensorflow.compat.v1 as tf and tf.disable_v2_behavior() at the top of train_model.py, test_model.py, and model2.py. This restores the tf.Session, tf.contrib.slim, and placeholder behavior that the original code requires.

Why do I get reshape errors with my custom dataset?

The generate_data.py script expects each line of your annotation file to contain exactly 196 floating-point values representing 98 facial landmarks (x,y pairs). If your annotations have fewer points, different delimiters, or missing values, the np.asarray call creates a shorter array that cannot fill the landmark_batch placeholder of shape (None, 196). Validate your data by asserting landmark.shape[0] == 196 after parsing.

How do I fix the AttributeError for phase_train?

The create_model function in model2.py requires a boolean placeholder named phase_train to control batch normalization statistics. If you call the model without this tensor, you will see ValueError: The placeholder tensor 'phase_train' does not exist. Explicitly create the placeholder before calling the model: phase_train = tf.placeholder(tf.bool, name='phase_train'), then pass it as an argument to create_model.

Is there a performance bottleneck in the original code?

Yes. The original train_model.py uses tf.map_fn to compute the Euler angle loss term 1 - tf.cos(abs(x)) for each sample individually. This Python-level loop prevents GPU vectorization and causes memory fragmentation. Replace the map_fn block with a fully vectorized operation: angle_loss = tf.reduce_sum(1.0 - tf.cos(tf.abs(euler_angles_gt_batch - euler_angles_pre)), axis=1). This change can reduce training time by 20–30% on modern GPUs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}